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void *thread_function(void *arg) { 
int my_number = *(int *)arg; 
int rand_num; 


printf ("thread_function is running. Argument was %d\n", my_number) ; 
rand_num=1+ (int) (9.0*rand() / (RAND_MAX+1.0)); 

sleep (rand_num) ; 

printf("Bye from d\n", my_number) ; 

pthread_exit (NULL) ; 


While in the main (original) thread, you wait to pick them up, but not in the order in which you 
created them: 


for(lots_of_threads = NUM_THREADS - 1; lots_of_threads >= 0; lots_of_threads--) 


res = pthread_join(a_thread[lots_of_threads], &thread_result) ; 
if (res == 0) { 
printf ("Picked up a thread\n"); 
} 
else { 
perror("pthread_join failed"); 


If you try to run the program with no sleep, you might see some strange effects, including some 
threads being started with the same argument; for example, you might see output similar to this: 


thread_function is running. Argument was 
thread_function is running. Argument was 
thread_function is running. Argument was 
thread_function is running. Argument was 
thread_function is running. Argument was 
thread_function is running. Argument was 
Waiting for threads to finish... 
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Bye from 5 

Picked up a thread 
Bye from 2 

Bye from 0 

Bye from 2 

Bye from 4 

Bye from 4 

Picked up a thread 
Picked up a thread 
Picked up a thread 
Picked up a thread 
Picked up a thread 
All done 


Did you spot why this could happen? The threads are being started using a local variable for the argument 
to the thread function. This variable is updated in the loop. The offending lines are 


for(lots_of_threads = 0; lots_of_threads < NUM_THREADS; lots_of_threads++) { 
res = pthread_create(&(a_thread[lots_of_threads]), NULL, 
thread_function, (void *)&lots_of_threads) ; 


If the main thread runs fast enough, it might alter the argument (lots_of_threads) for some of the 
threads. Behavior like this arises when not enough care is taken with shared variables and multiple exe- 
cution paths. We did warn you that programming threads required careful attention to design! To correct 
the problem, you need to pass the value directly like this: 


res = pthread_create(&(a_thread[lots_of_threads]), NULL, thread_function, (void 
*)lots_of_threads) ; 


and of course change thread_function: 


void *thread_function(void *arg) { 
int my_number = (int)arg; 


This is shown in the program thread8a.c, with the changes highlighted: 


#include <stdio.h> 

#include <unistd.h> 
#include <stdlib.h> 
#include <string.h> 
#include <pthread.h> 


#define NUM_THREADS 6 
void *thread_function(void *arg); 
int main() { 

int res; 

pthread_t a_thread[NUM_THREADS] ; 


void *thread_result; 
int lots_of_threads; 
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for(lots_of_threads = 0; lots_of_threads < NUM_THREADS; lots_of_threads++) { 





res = pthread_create(&(a_thread[lots_of_threads]), NULL, 
thread_function, (void *)lots_of_threads) ; 
ie (Gees LS O) ff 


perror ("Thread creation failed"); 
exit (EXIT_FAILURE) ; 








} 


printf ("Waiting for threads to finish...\n"); 


for(lots_of_threads = NUM_THREADS - 1; lots_of_threads >= 0; lots_of_threads--) { 
res = pthread_join(a_thread[lots_of_threads], &thread_result) ; 
if (res == 0) { 
printf ("Picked up a thread\n"); 
} else { 


perror("pthread_join failed"); 
} 
} 


printf("All done\n") ; 





exit (EXIT_SUCCESS) ; 
} 


void *thread_function(void *arg) { 
int my_number = (int)arg; 
int rand_num; 


printf ("thread_function is running. Argument was %d\n", my_number) ; 
rand_num=1+ (int) (9.0*rand() / (RAND_MAX+1.0)); 

sleep (rand_num) ; 

printf("Bye from d\n", my_number) ; 


pthread_exit (NULL) ; 


Summary 


In this chapter, you learned how to create several threads of execution inside a process, where each thread 
shares file scope variables. You looked at the two ways that threads can control access to critical code and 
data, using both semaphores and mutexes. Next, you saw how to control the attributes of threads and, in 
particular, how you could separate them from the main thread so that it no longer had to wait for threads 
that it had created to complete. After a quick look at how one thread can request another to finish and at 
how the receiving thread can manage such requests, we presented an example of a program with many 
simultaneous threads executing. 


We haven't had the space to cover every last function call and nuance associated with threads, but you 


should now have sufficient understanding to start writing your own programs with threads and to 
investigate the more esoteric aspects of threads by reading the manual pages. 
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13 


Inter-Process 
Communication: Pipes 





In Chapter 11, you saw a very simple way of sending messages between two processes using signals. 
You created notification events that could be used to provoke a response, but the information trans- 
ferred was limited to a signal number. 


In this chapter, you take a look at pipes, which allow more useful data to be exchanged between 
processes. By the end of the chapter, you'll be using your newfound knowledge to re-implement 
the CD database program as a very simple client/server application. 


We cover the following topics in this chapter: 


The definition of a pipe 
Process pipes 

Pipe calls 

Parent and child processes 


Named pipes: FIFOs 





COocooco do 


Client/server considerations 


What Is a Pipe? 


We use the term pipe to mean connecting a data flow from one process to another. Generally you 
attach, or pipe, the output of one process to the input of another. 


Most Linux users will already be familiar with the idea of a pipeline, linking shell commands 
together so that the output of one process is fed straight to the input of another. For shell com- 


mands, this is done using the pipe character to join the commands, such as 


cmd1 | cmd2 
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The shell arranges the standard input and output of the two commands, so that 


Q The standard input to cmd1 comes from the terminal keyboard. 


Q = The standard output from cmd1 is fed to cmd2 as its standard input. 





Q The standard output from cmd2 is connected to the terminal screen. 
What the shell has done, in effect, is reconnect the standard input and output streams so that data flows 


from the keyboard input through the two commands and is then output to the screen. See Figure 13-1 for 
a visual representation of this process. 


standard standard 
input output 
Ere! 


In this chapter, you see how to achieve this effect within a program and how you can use pipes to connect 
multiple processes to allow you to implement a simple client/server system. 




















Figure 13-1 

















Process Pipes 


Perhaps the simplest way of passing data between two programs is with the popen and pclose functions. 
These have the following prototypes: 


#include <stdio.h> 


FILE *popen(const char *command, const char *open_mode) ; 
int pclose(FILE *stream_to_close) ; 


popen 


The popen function allows a program to invoke another program as a new process and either pass data 
to it or receive data from it. The command string is the name of the program to run, together with any 
parameters. open_mode must be either "r" or "w". 


If the open_mode is "r", output from the invoked program is made available to the invoking program 
and can be read from the file stream FILE * returned by popen, using the usual stdio library functions 
for reading (for example, fread). However, if open_mode is "w", the program can send data to the 
invoked command with calls to fwrite. The invoked program can then read the data on its standard 
input. Normally, the program being invoked won’t be aware that it’s reading data from another process; 
it simply reads its standard input stream and acts on it. 
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A call to popen must specify either "r" or "w"; no other option is supported in a standard implementa- 
tion of popen. This means that you can’t invoke another program and both read from and write to it. On 
failure, popen returns a null pointer. If you want bidirectional communication using pipes, the normal 
solution is to use two pipes, one for data flow in each direction. 


pclose 


When the process started with popen has finished, you can close the file stream associated with it using 
pclose. The pclose call will return only when the process started with popen finishes. If it’s still run- 
ning when pclose is called, the pclose call will wait for the process to finish. 


The pclose call normally returns the exit code of the process whose file stream it is closing. If the invoking 
process has already executed a wait statement before calling pclose, the exit status will be lost because 
the invoked process has finished and pclose will return -1, with errno set to ECHILD. 


Try It Out Reading Output from an External Program 


Let’s try a simple popen and pclose example, popen1 .c. You'll use popen in a program to access infor- 
mation from uname. The uname -a command prints system information, including the machine type, 
the OS name, version and release, and the machine’s network name. 


Having initialized the program, you open the pipe to uname, making it readable and setting read_fp to 
point to the output. At the end, the pipe pointed to by read_fp is closed. 


#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 


int main() 
{ 
FILE *read_fp; 
char buffer[BUFSIZ + 1]; 
int chars_read; 
memset (buffer, '\0', sizeof (buffer) ); 
read_fp = popen("uname -a", "r"); 
if (read_fp != NULL) { 
chars_read = fread(buffer, sizeof(char), BUFSIZ, read_fp); 
if (chars_read > 0) { 
printf ("Output was:-\n%s\n", buffer) ; 
i 
pclose(read_fp); 
exit (EXIT_SUCCESS) ; 





} 
exit (EXIT_FAILURE); 





When you run this program, you should get output like the following (from one of the authors’ machines): 


$ ./popen1 

Output was:- 

Linux suse103 2.6.20.2-2-default #1 SMP Fri Mar 9 21:54:10 UTC 2007 i686 i686 i386 
GNU/Linux 


527 


Chapter 13: Inter-Process Communication: Pipes 


How It Works 


The program uses the popen call to invoke the uname command with the -a parameter. It then uses the 
returned file stream to read data up to BUFSIZ characters (as this is a #define from stdio.h) and then 
prints it out so it appears on the screen. Because you've captured the output of uname inside a program, 
it’s available for processing. 


Sending Output to popen 


Now that you’ve seen an example of capturing output from an external program, let’s look at sending 


output to an external program. Here’s a program, popen2 .c, that pipes data to another. Here, you'll use 
od (octal dump). 


Try It Out 


Have a look at the following code; you can see that it is very similar to the preceding example, except 
you are writing down a pipe instead of reading from it. This is popen2 .c. 


Sending Output to an External Program 


#include 
#include 
#include 
#include 


<unistd.h> 
<stdlib.h> 
<stdio.h> 

<string.h> 


int main() 


{ 





FILE *write_fp; 
char butfer[BUFSEZ + 1]; 


sprintf (buffer, "Once upon a time, 
write_fp = popen("od -c", "w"); 
if (write_fp != NULL) { 
fwrite(buffer, sizeof(char), 
pclose(write_fp); 
exit (EXIT_SUCCESS) ; 


there was...\n"); 
strlen (buffer), write_fp); 


} 
exit (EXIT_FAILURE) ; 


When you run this program, you should get the following output: 


$ ./popen2 
0000000 O n c e u p o n a t a: m e 
0000020 t h e r e w a s \n 
0000037 

How It Works 


The program uses popen with the parameter "w" to start the od -c command, so that it can send data to 
that command. It then sends a string that the od -c command receives and processes; the od -c com- 
mand then prints the result of the processing on its standard output. 
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From the command line, you can get the same output with the command 


$ echo "Once upon a time, there was..." | od -c 


Passing More Data 


The mechanism that you’ve used so far simply sends or receives all the data in a single fread or 
fwrite. Sometimes you may want to send the data in smaller pieces, or perhaps you may not know the 
size of the output. To avoid having to declare a very large buffer, you can just use multiple fread or 
fwrite calls and process the data in parts. 


Here’s a program, popen3 .c, that reads all of the data from a pipe. 


Try It Out Reading Larger Amounts of Data from a Pipe 


In this program, you read data from an invoked ps ax process. There’s no way to know in advance how 
much output there will be, so you must allow for multiple reads of the pipe. 


#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 


int main() 

{ 
FILE *read_fp; 
char buffer[BUFSIZ + 1]; 
int chars_read; 


memset (buffer, '\0', sizeof (buffer) ); 
read_fp = popen("ps ax", "r"); 
if (read_fp != NULL) { 
chars_read = fread(buffer, sizeof(char), BUFSIZ, read_fp); 
while (chars_read > 0) { 
bukrernlcharssread m MESEN 
printf ("Reading %d:-\n %s\n", BUFSIZ, buffer); 
chars_read = fread(buffer, sizeof(char), BUFSIZ, read_fp); 
} 
pclose(read_fp); 
exit (EXIT_SUCCESS) ; 





} 
exit (EXIT_FAILURE) ; 





The output, edited for brevity, is similar to this: 


S ./popen3 
Reading 1024:- 
PID TTY STAT TIME COMMAND 
1 ? Ss 0:03 init [5] 
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2 ? SW 0:00 [kflushd] 

3 ? SW 0:00 [kpiod] 

4 ? SW 0:00 [kswapd] 

5 ? SW< 0:00 [mdrecoveryd] 


240 tty2 Ss 0:02 emacs draftl.txt 
Reading 1024:- 

368 ttyl S 0:00 ./popen3 

369 ttyl R 0:00 ps -ax 


How It Works 


The program uses popen with an "x" parameter in a similar fashion to popen1 .c. This time, it continues 
reading from the file stream until there is no more data available. Notice that, although the ps command 
takes some time to execute, Linux arranges the process scheduling so that both programs run when they 
can. If the reader process, popen3, has no input data, it’s suspended until some becomes available. If the 
writer process, ps, produces more output than can be buffered, it’s suspended until the reader has con- 
sumed some of the data. 


In this example, you may not see Reading: - output a second time. This will be the case if BUFSIZ is 
greater than the length of the ps command output. Some (mostly more recent) Linux systems set BUFSIZ 
as high as 8,192 or even higher. To test that the program works correctly when reading several chunks of 
output, try reading less than BUFSIZ, maybe BUFSIZE/10, characters at a time. 





How popen Is Implemented 


The popen call runs the program you requested by first invoking the shell, sh, passing it the command 
string as an argument. This has two effects, one good and the other not so good. 


In Linux (as in all UNIX-like systems), all parameter expansion is done by the shell, so invoking the shell to 
parse the command string before the program is invoked allows any shell expansion, such as determining 
what files * .c actually refers to, to be done before the program starts. This is often quite useful, and it 
allows complex shell commands to be started with popen. Other process creation functions, such as execl, 
can be much more complex to invoke, because the calling process has to perform its own shell expansion. 


The unfortunate effect of using the shell is that for every call to popen, a shell is invoked along with the 
requested program. Each call to popen then results in two extra processes being started, which makes 
the popen function a little expensive in terms of system resources and invocation of the target command 
is slower than it might otherwise have been. 


Here’s a program, popen4 .c, that you can use to demonstrate the behavior of popen. You can count the 
lines in all the popen example source files by cating the files and then piping the output to wc -1, 
which counts the number of lines. On the command line, the equivalent command is 


$ cat popen*.c | we -1 


Actually, wc -1 popen* .c is easier to type and much more efficient, but the example serves to illus- 
trate the principle. 
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Try It Out popen Starts a Shell 


This program uses exactly the preceding command, but through popen so that it can read the result: 


#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 


int main() 

{ 
FILE *read_fp; 
char buffer[BUFSIZ + 1]; 
int chars_read; 


memset (buffer, '\0', sizeof (buffer) ); 
read_fp = popen("cat popen*.c | Wie Se Sale 
if (read_fp != NULL) { 
chars_read = fread(buffer, sizeof(char), BUFSIZ, read_fp); 
while (chars_read > 0) { 
buffer[chars_read - 1] = '\0'; 
printf ("Reading:-\n %s\n", buffer); 
chars_read = fread(buffer, sizeof(char), BUFSIZ, read_fp); 
} 
pclose(read_fp); 
exit (EXIT_SUCCESS) ; 





} 
exit (EXIT_FAILURE); 





When you run this program, the output is 


$ ./popen4 
Reading: - 
94 


How It Works 


The program shows that the shell is being invoked to expand popen* .c to the list of all files starting 
popen and ending in .c and also to process the pipe (|) symbol and feed the output from cat into we. 
You invoke the shell, the cat program, and we and cause an output redirection, all in a single popen call. 
The program that invokes the command sees only the final output. 


The Pipe Call 


You’ve seen the high-level popen function, but now let’s move on to look at the lower-level pipe func- 
tion. This function provides a means of passing data between two programs, without the overhead of 
invoking a shell to interpret the requested command. It also gives you more control over the reading and 
writing of data. 
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The pipe function has the following prototype: 

#include <unistd.h> 

int pipe(int file _descriptor[2]); 
pipe is passed (a pointer to) an array of two integer file descriptors. It fills the array with two new file 
descriptors and returns a zero. On failure, it returns -1 and sets errno to indicate the reason for failure. 


Errors defined in the Linux manual page for pipe (in section 2 of the manual) are 


Q EMFILE: Too many file descriptors are in use by the process. 








Qo = ENFILE: The system file table is full. 











Q EFAULT: The file descriptor is not valid. 


The two file descriptors returned are connected in a special way. Any data written to £ile_descriptor [1] 
can be read back from £ile_descriptor [0]. The data is processed in a first in, first out basis, usually 
abbreviated to FIFO. This means that if you write the bytes 1, 2, 3 to file_descriptor [1], reading from 
file_descriptor [0] will produce 1, 2, 3. This is different from a stack, which operates on a last in, first out 
basis, usually abbreviated to LIFO. 


It’s important to realize that these are file descriptors, not file streams, so you must use the lower- 
level read and write system calls to access the data, rather than the stream library functions 
fread and fwrite. 


Here’s a program, pipel .c, that uses pipe to create a pipe. 


Try It Out The pipe Function 


The following example is pipe1 .c. Note the £ile_pipes array, the address of which is passed to the 
pipe function asa parameter. 


#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 


int main() 
{ 
int data_processed; 
int file_pipes[2]; 
const char some_data[] = "123"; 
char buffer[BUFSIZ + 1]; 


memset (buffer, '\0', sizeof(buffer) ); 


if (pipe(file_pipes) == 0) { 
data_processed = write(file_pipes[1], some_data, strlen(some_data) ); 
printf ("Wrote %d bytes\n", data_processed) ; 
data_processed = read(file_pipes[0], buffer, BUFSIZ); 
printf("Read %d bytes: %s\n", data_processed, buffer) ; 
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exit (EXIT_SUCCESS) ; 
} 
exit (EXIT_FAILURE) ; 





When you run this program, the output is 


$ ./pipel 
Wrote 3 bytes 
Read 3 bytes: 123 


How It Works 


The program creates a pipe using the two file descriptors in the array £ile_pipes[]. It then writes data 
into the pipe using the file descriptor £ile_pipes[1] and reads it back from f£ile_pipes [0]. Notice 
that the pipe has some internal buffering that stores the data in between the calls to write and read. 


You should be aware that the effect of trying to write using £ile_descriptor [0], or read using 
£ile_descriptor [1], is undefined, so the behavior could be very strange and may change without 
warning. On the authors’ systems, such calls fail with a -1 return value, which at least ensures that it’s 
easy to catch this mistake. 


At first glance, this example of a pipe doesn’t seem to offer us anything that we couldn’t have done with 
a simple file. The real advantage of pipes comes when you want to pass data between two processes. As 
you saw in Chapter 12, when a program creates a new process using the fork call, file descriptors that 
were previously open remain open. By creating a pipe in the original process and then forking to create 
a new process, you can pass data from one process to the other down the pipe. 





Try It Out Pipes across a fork 


1. = This is pipe2.c. It starts rather like the first example, up until you make the call to fork. 


#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 


int main() 
{ 
int data_processed; 
int file_pipes[2]; 
const char some_data[] = "123"; 
char buffer[BUFSIZ + 1]; 
pid_t fork_result; 


memset (buffer, '\0', sizeof (buffer) ); 


if (pipe(file_pipes) == 0) { 
fork_result = £ork(); 
HERC EOrka resulta mA 
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fprintf(stderr, "Fork failure") ; 
exit (EXIT_FAILURE) ; 
} 


2. You’ve made sure the fork worked, so if fork_result equals zero, you're in the child process: 


IE (fork result == 0) f 
data_processed = read(file_pipes[0], buffer, BUFSIZ); 
printf("Read %d bytes: %s\n", data_processed, buffer); 
exit (EXIT_SUCCESS) ; 

} 


3. Otherwise, you must be in the parent process: 


else { 
data_processed = write(file_pipes[1], some_data, 
strlen(some_data) ) ; 
printf("Wrote %d bytes\n", data_processed) ; 
} 
} 
exit (EXIT_SUCCESS) ; 


} 
When you run this program, the output is, as before, 


$ ./pipe2 
Wrote 3 bytes 
Read 3 bytes: 123 


You may find that in practice the command prompt reappears before the last part of the output because 
the parent will finish before the child, so we have tidied the output here to make it easier to read. 


How It Works 


First, the program creates a pipe with the pipe call. It then uses the fork call to create a new process. 

If the fork was successful, the parent writes data into the pipe, while the child reads data from the pipe. 
Both parent and child exit after a single write and read. If the parent exits before the child, you might 
see the shell prompt between the two outputs. 


Although the program is superficially very similar to the first pipe example, we’ve taken a big step for- 
ward by being able to use separate processes for the reading and writing, as illustrated in Figure 13-2. 





file_pipes[1] file_pipes[0] 







Child 
process 


Parent 
process 
















Figure 13-2 
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Parent and Child Processes 


The next logical step in our investigation of the pipe call is to allow the child process to be a different 
program from its parent, rather than just a different process running the same program. You do this 
using the exec call. One difficulty is that the new execed process needs to know which file descriptor 
to access. In the previous example, this wasn’t a problem because the child had access to its copy of the 
£ile_pipes data. After an exec call, this will no longer be the case, because the old process has been 
replaced by the new child process. You can get around this by passing the file descriptor (which is, after 
all, just a number) as a parameter to the newly execed program. 


To show how this works, you need two programs. The first is the data producer. It creates the pipe and 
then invokes the child, the data consumer. 


Try It Out Pipes and exec 


{. For the first program, you adapt pipe2.c to pipe3 .c. The changed lines are shown shaded: 


#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 


int main() 


{ 


int data_processed; 

int file_pipes[2]; 

const char some_data[] = "123"; 
char buffer[BUFSIZ + 1]; 

pid_t fork_result; 


memset (buffer, '\0', sizeof (buffer) ); 


if (pipe(file_pipes) == 0) { 
fork_result = fork(); 
if (fork_result == (pid_t)-1) { 
fprintf(stderr, "Fork failure") ; 
exit (EXIT_FAILURE) ; 





} 


if (fork_result == 0) { 
sprintf (buffer, "td", file_pipes[0]); 
(void) execl("pipe4", "pipe4", buffer, (char *)0); 
exit (EXIT_FAILURE) ; 

} 

else { 
data_processed = write(file_pipes[1], some_data, 

strlen(some_data) ) ; 

printf("%d - wrote %d bytes\n", getpid(), data_processed) ; 





EXIT_SUCCESS) ; 








exit ( 
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2. The consumer program, pipe4 .c, which reads the data, is much simpler: 


#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 


int main(int argc, char *argv[]) 
{ 
int data_processed; 
char buffer[BUFSIZ + 1]; 
int file_descriptor; 


memset (buffer, '\0', sizeof(buffer) ); 
sscanf(argv[1], "%d", &file_descriptor) ; 
data_processed = read(file_descriptor, buffer, BUFSIZ); 


printf("Sd - read %d bytes: %s\n", getpid(), data_processed, buffer) ; 
exit (EXIT_SUCCESS) ; 


Remembering that pipe3 invokes the pipe4 program, you get something similar to the following out- 
put when you run pipe3: 


$ ./pipe3 
22460 - wrote 3 bytes 
22461 - read 3 bytes: 123 


How It Works 


The pipe3 program starts like the previous example, using the pipe call to create a pipe and then using 
the fork call to create a new process. It then uses sprintf to store the “read” file descriptor number of the 
pipe in a buffer that will form an argument of piped. 


A call to exec! is used to invoke the pipe4 program. The arguments to exec1 are 


The program to invoke 
argv [0], which takes the program name 


argv [1], which contains the file descriptor number you want the program to read from 





Coo o 


(char *) 0, which terminates the parameters 


The pipe4 program extracts the file descriptor number from the argument string and then reads from 
that file descriptor to obtain the data. 


Reading Closed Pipes 


Before we move on, we need to look a little more carefully at the file descriptors that are open. Up to this 
point you have allowed the reading process simply to read some data and then exit, assuming that Linux 
will clean up the files as part of the process termination. 
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Most programs that read data from the standard input do so differently than the examples you’ve seen 
so far. They don’t usually know how much data they have to read, so they will normally loop — reading 
data, processing it, and then reading more data until there’s no more data to read. 


A read call will normally block; that is, it will cause the process to wait until data becomes available. If 
the other end of the pipe has been closed, then no process has the pipe open for writing, and the read 
blocks. Because this isn’t very helpful, a read on a pipe that isn’t open for writing returns zero rather 
than blocking. This allows the reading process to detect the pipe equivalent of end of file and act appro- 
priately. Notice that this isn’t the same as reading an invalid file descriptor, which read considers an 
error and indicates by returning —1. 


If you use a pipe across a fork call, there are two different file descriptors that you can use to write to 
the pipe: one in the parent and one in the child. You must close the write file descriptors of the pipe in 
both parent and child processes before the pipe is considered closed and a read call on the pipe will fail. 
You'll see an example of this later when we return to this subject in more detail to look at the O_NON- 
BLOCK flag and FIFOs. 


Pipes Used as Standard Input and Output 


Now that you know how to make a read on an empty pipe fail, you can look at a much cleaner method 
of connecting two processes with a pipe. You arrange for one of the pipe file descriptors to have a known 
value, usually the standard input, 0, or the standard output, 1. This is slightly more complex to set up in 
the parent, but it allows the child program to be much simpler. 


The one big advantage is that you can invoke standard programs, ones that don’t expect a file descriptor 
as a parameter. In order to do this, you need to use the dup function, which you met in Chapter 3. There 
are two closely related versions of dup that have the following prototypes: 


#include <unistd.h> 


int dup(int file descriptor) ; 
int dup2(int file _descriptor_one, int file _descriptor_two); 


The purpose of the dup call is to open a new file descriptor, a little like the open call. The difference is 
that the new file descriptor created by dup refers to the same file (or pipe) as an existing file descriptor. 
In the case of dup, the new file descriptor is always the lowest number available, and in the case of dup2 
it’s the same as, or the first available descriptor greater than, the parameter £ile_descriptor_two. 


You can get the same effect as dup and dup2 by using the more general £cnt1 call, with a command 
F_DUPFD. Having said that, the dup call is easier to use because it’s tailored specifically to the needs 
of creating duplicate file descriptors. It’s also very commonly used, so you'll find it more frequently in 
existing programs than £cnt1 and F_DUPFD. 


So how does dup help in passing data between processes? The trick is knowing that the standard input file 
descriptor is always 0 and that dup always returns a new file descriptor using the lowest available number. 
By first closing file descriptor 0 and then calling dup, the new file descriptor will have the number 0. Because 
the new descriptor is a duplicate of an existing one, standard input will have been changed to access the file 
or pipe whose file descriptor you passed to dup. You will have created two file descriptors that refer to the 
same file or pipe, and one of them will be the standard input. 
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File Descriptor Manipulation by close and dup 


The easiest way to understand what happens when you close file descriptor 0, and then call dup, is to 
look at how the state of the first four file descriptors changes during the sequence. This is shown in the 
following table. 


File Descriptor Initially After close of File After dup 
Number Descriptor 0 

0 Standard input {closed} Pipe file descriptor 
1 Standard output Standard output Standard output 

2 Standard error Standard error Standard error 

3 Pipe file descriptor Pipe file descriptor Pipe file descriptor 


Try It Out Pipes and dup 


Let’s return to the previous example, but this time you'll arrange for the child program to have its stdin 
file descriptor replaced with the read end of the pipe you create. You'll also do some tidying up of file 
descriptors so the child program can correctly detect the end of the data in the pipe. As usual, we'll omit 
some error checking for the sake of brevity. 


Modify pipe3 .c to pipe5.c using the following code: 


#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 


int main() 
{ 
int data_processed; 
int file_pipes[2]; 
const char some_data[] = "123"; 
pid_t fork_result; 


if (pipe(file_pipes) == 0) { 
fork_result = fork(); 
if (fork_result == (pid_t)-1) { 
fprintf(stderr, "Fork failure"); 
exit (EXIT_FAILURE); 
} 


if (fork_result == (pid_t)0) { 
close(0); 
dup (file_pipes[0]); 
close(file_pipes[0]); 
close(file_pipes[1]); 
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execlp("od", "od", "-c", (char *)0); 
exit (EXIT_FAILURE) ; 





} 
else { 
close(file_pipes[0]); 
data_processed = write(file_pipes[1], some_data, 
strlen(some_data) ) ; 
close(file_pipes[1]); 
printf ("%d - wrote %d bytes\n", (int)getpid(), data_processed) ; 
} 
} 
exit (EXIT_SUCCESS) ; 





} 
The output from this program is 


S ./pipe5 

22495 - wrote 3 bytes 
0000000 1 2 3 
0000003 


How It Works 


As before, the program creates a pipe and then forks, creating a child process. At this point, both the parent 
and child have file descriptors that access the pipe, one each for reading and writing, so there are four open 
file descriptors in total. 


Let’s look at the child process first. The child closes its standard input with close (0) and then calls 

dup (file_pipes[0]). This duplicates the file descriptor associated with the read end of the pipe as 
file descriptor 0, the standard input. The child then closes the original file descriptor for reading from the 
pipe, £ile_pipes [0]. Because the child will never write to the pipe, it also closes the write file descrip- 
tor associated with the pipe, file_pipes[1]. It now has a single file descriptor associated with the pipe: 
file descriptor 0, its standard input. 


The child can then use exec to invoke any program that reads standard input. In this case, you use the 
od command. The od command will wait for data to be available to it as if it were waiting for input from 
a user terminal. In fact, without some special code to explicitly detect the difference, it won’t know that 
the input is from a pipe rather than a terminal. 


The parent starts by closing the read end of the pipe £ile_pipes [0], because it will never read the 
pipe. It then writes data to the pipe. When all the data has been written, the parent closes the write end 
of the pipe and exits. Because there are now no file descriptors open that could write to the pipe, the od 
program will be able to read the three bytes written to the pipe, but subsequent reads will then return 0 
bytes, indicating an end of file. When the read returns 0, the od program exits. This is analogous to run- 
ning the od command on a terminal, then pressing Ctrl+D to send end of file to the od command. 


Figure 13-3 shows the sequence after the call to the pipe, Figure 13-4 shows the sequence after the call to 
fork, and Figure 13-5 represents the program when it’s ready to transfer data. 
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Named Pipes: FIFOs 


So far, you have only been able to pass data between related programs, that is, programs that have been 
started from a common ancestor process. Often this isn’t very convenient, because you would like unre- 
lated processes to be able to exchange data. 


You do this with FIFOs, often referred to as named pipes. A named pipe is a special type of file (remember 


that everything in Linux is a file!) that exists as a name in the file system but behaves like the unnamed 
pipes that you’ve met already. 
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You can create named pipes from the command line and from within a program. Historically, the com- 
mand-line program for creating them was mknod: 


$ mknod filename p 


However, the mknod command is not in the X/Open command list, so it may not be available on all 
UNIX-like systems. The preferred command-line method is to use 


$ mkfifo filename 


Some older versions of UNIX only had the mknod command. X/Open Issue 4 Version 2 has the 
mknod function call, but not the command-line program. Linux, friendly as ever, supplies both 
mknod and mkfifo. 


From inside a program, you can use two different calls: 


#include <sys/types.h> 
#include <sys/stat.h> 


int mkfifo(const char *filename, mode_t mode); 
int mknod(const char *filename, mode_t mode | S_IFIFO, (dev_t) 0); 


Like the mknod command, you can use the mknod function for making many special types of files. Using 
a dev_t value of 0 and ORing the file access mode with S_IFIFO is the only portable use of this function 
that creates a named pipe. We'll use the simpler mk£ifo function in the examples. 


Try It Out Creating a Named Pipe 


The following example is £ifo1.c: 


#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <sys/types.h> 
#include <sys/stat.h> 


int main() 

{ 
shale, Ties! = Mie EO EPAM EO OE 
if (res == 0) printf("FIFO created\n") ; 
exit (EXIT_SUCCESS) ; 





You can create and look for the pipe with 


S ./£ifo1 

FIFO created 

S$ ls -1F /tmp/my_fifo 

prwxr-xr-x 1 rick users 0 2007-06-16 17:18 /tmp/my_fifo| 
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Notice that the first character of output is a p, indicating a pipe. The | symbol at the end is added by the 
1s command's -F option and also indicates a pipe. 


How It Works 


The program uses the mk£i£o function to create a special file. Although you ask for a mode of 0777, this 
is altered by the user mask (umask) setting (in this case 022), just as in normal file creation, so the resulting 
file has mode 755. If your umask is set differently, for example to 0002, you will see different permissions 
on the created file. 


You can remove the FIFO just like a conventional file by using the rm command, or from within a program 
by using the unlink system call. 


Accessing a FIFO 


One very useful feature of named pipes is that, because they appear in the file system, you can use them 
in commands where you would normally use a filename. Before you do more programming using the 
FIFO file you created, let’s investigate the behavior of the FIFO file using normal file commands. 


Try It Out Accessing a FIFO File 
1. First, try reading the (empty) FIFO: 


S$ cat < /tmp/my_fifo 


2. Now try writing to the FIFO. You will have to use a different terminal because the first com- 
mand will now be hanging, waiting for some data to appear in the FIFO. 


S$ echo "Hello World" > /tmp/my_fifo 


You will see the output appear from the cat command. If you don’t send any data down the 
FIFO, the cat command will hang until you interrupt it, conventionally with Ctrl+C. 
3. You can do both at once by putting the first command in the background: 
$ cat < /tmp/my_fifo & 
[1] 1316 


$ echo "Hello World" > /tmp/my_fifo 
Hello World 


[1]+ Done cat </tmp/my_fifo 
$ 


How It Works 


Because there was no data in the FIFO, the cat and echo programs both block, waiting for some data to 
arrive and some other process to read the data, respectively. 


Looking at the third stage, the cat process is initially blocked in the background. When echo makes 
some data available, the cat command reads the data and prints it to the standard output. Notice that 
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the cat program then exits without waiting for more data. It doesn’t block because the pipe will have 
been closed when the second command putting data in the FIFO completed, so calls to read in the cat 
program will return 0 bytes, indicating the end of file. 


Now that you’ve seen how the FIFO behaves when you access it using command-line programs, let’s 
look in more detail at the program interface, which allows you more control over how reads and writes 
behave when you're accessing a FIFO. 


Unlike a pipe created with the pipe call, a FIFO exists as a named file, not as an open file descriptor, 
and it must be opened before it can be read from or written to. You open and close a FIFO using the 
same open and close functions that you saw used earlier for files, with some additional functionality. 
The open call is passed the path name of the FIFO, rather than that of a regular file. 


Opening a FIFO with open 


The main restriction on opening FIFOs is that a program may not open a FIFO for reading and writing 
with the mode O_RDWR. If a program violates this restriction, the result is undefined. This is quite a sensi- 
ble restriction because, normally, you use a FIFO only for passing data in a single direction, so there is 
no need for an O_RDWR mode. A process would read its own output back from a pipe if it were opened 
read/write. 


If you do want to pass data in both directions between programs, it’s much better to use either a pair of 
FIFOs or pipes, one for each direction, or (unusually) explicitly change the direction of the data flow by 
closing and reopening the FIFO. We return to bidirectional data exchange using FIFOs later in the chapter. 
The other difference between opening a FIFO and a regular file is the use of the open_flag (the second 
parameter to open) with the option O_NONBLOCK. Using this open mode not only changes how the open call 


is processed, but also changes how read and write requests are processed on the returned file descriptor. 


There are four legal combinations of O_RDONLY, O_WRONLY, and the O_NONBLOCK flag. We’ll consider 
each in turn. 


open(const char *path, O_RDONLY) ; 


In this case, the open call will block; it will not return until a process opens the same FIFO for writing. 
This is like the first cat example. 


open(const char *path, O_RDONLY | O_NONBLOCK) ; 


The open call will now succeed and return immediately, even if the FIFO has not been opened for writing 
by any process. 


open(const char *path, O_WRONLY) ; 
In this case, the open call will block until a process opens the same FIFO for reading. 


open(const char *path, O_WRONLY | O_NONBLOCK) ; 
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This will always return immediately, but if no process has the FIFO open for reading, open will return 
an error, —1, and the FIFO won’t be opened. If a process does have the FIFO open for reading, the file 
descriptor returned can be used for writing to the FIFO. 


Notice the asymmetry between the use of O_LNONBLOCK with O_RDONLY and O_WRONLY, in that a non- 
blocking open for writing fails if no process has the pipe open for reading, but a nonblocking read 
doesn't fail. The behavior of the close call isn’t affected by the O_NONBLOCX flag. 


Try It Out Opening FIFO Files 


Now look at how you can use the behavior of open with the O_NONBLOCK flag to synchronize two 
processes. Rather than use a number of example programs, you'll write a single test program, fifo2.c, 
which allows you to investigate the behavior of FIFOs by passing in different parameters. 


1. Start with the header files, a #define, and the check that the correct number of command-line 
arguments has been supplied: 


#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 
#include <fcntl.h> 
#include <sys/types.h> 
#include <sys/stat.h> 


#define FIFO_NAME "/tmp/my_fifo" 


int main(int argc, char *argv[]) 
{ 

int res; 

int open_mode = 0; 

aio ees. 


wit (ance < 2) * 
fprintf(stderr, "Usage: %s <some combination of\ 
O_RDONLY O_WRONLY O_NONBLOCK>\n", *argv); 
exit (EXIT_FAILURE) ; 


2. Assuming that the program passed the test, you now set the value of open_mode from those 
arguments: 


fe Quire (cle eclectic] Gel tt) me 
if (strnemp(*++argv, "O_RDONLY", 8) == 0) 
open_mode |= O_RDONLY; 
if (strncemp(*argv, "O_WRONLY", 8) == 0) 
open_mode |= O_WRONLY; 
if (strnemp(*argv, "O_NONBLOCK", 10) == 0) 
open_mode |= O_NONBLOCK; 
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Next check whether the FIFO exists, and create it if necessary. Then the FIFO is opened and out- 
put given to that effect while the program catches forty winks. Last of all, the FIFO is closed. 


if (access (FIFO_NAME, F_OK) == -1) { 
res = mkfifo(FIFO_NAME, 0777); 
aie (assy I ©) tf 
fprintf(stderr, "Could not create fifo %s\n", FIFO_NAME) ; 
exit (EXIT_FAILURE) ; 








} 


printf("Process %d opening FIFO\n", getpid()); 
res = open(FIFO_NAME, open_mode) ; 
printf("Process %d result %d\n", getpid(), res); 
sleep (5); 

if (res != -1) (void)close(res) ; 

printf("Process %d finished\n", getpid()); 

exit (EXIT_SUCCESS) ; 





How It Works 


This program allows you to specify on the command line the combinations of O_RDONLY, O_WRONLY, and 
O_NONBLOCK that you want to use. It does this by comparing known strings with command-line parame- 
ters and setting (with |=) the appropriate flag if the string matches. The program uses the access func- 
tion to check whether the FIFO file already exists and will create it if required. 


You never destroy the FIFO, because you have no way of telling if another program already has the FIFO 


in use. 


O_RDONLY and O_WRONLY without O_NONBLOCK 


You now have your test program, so you can try out a couple of combinations. Notice that the first pro- 
gram, the reader, has been put in the background: 


$ ./£if02 O_RDONLY & 


[1] 


152 


Process 152 opening FIFO 
$ ./£i1£02 O_WRONLY 
Process 153 opening FIFO 
Process 152 result 3 
Process 153 result 3 
Process 152 finished 
Process 153 finished 


This is probably the most common use of named pipes. It allows the reader process to start and wait in 
the open call and then allows both programs to continue when the second program opens the FIFO. 
Notice that both the reader and writer processes have synchronized at the open call. 


When a Linux process is blocked, it doesn’t consume CPU resources, so this method of process synchro- 
nization is very CPU-efficient. 
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O_RDONLY with O_NONBLOCK and O_WRONLY 


In the following example, the reader process executes the open call and continues immediately, even 
though no writer process is present. The writer also immediately continues past the open call, because 
the FIFO is already open for reading. 


$ ./£i£02 O_RDONLY O_NONBLOCK & 

[1] 160 

Process 160 opening FIFO 

$ ./£i1£02 O_WRONLY 

Process 161 opening FIFO 

Process 160 result 3 

Process 161 result 3 

Process 160 finished 

Process 161 finished 

[1]+ Done ./£if02 O_RDONLY O_NONBLOCK 


These two examples are probably the most common combinations of open modes. Feel free to use the 
example program to experiment with some other combinations. 


Reading and Writing FIFOs 


Using the O_NONBLOCK mode affects how read and write calls behave on FIFOs. 


A read on an empty blocking FIFO (that is, one not opened with O_NONBLOCK) will wait until some data 
can be read. Conversely, a read on a nonblocking FIFO with no data will return 0 bytes. 


A write on a full blocking FIFO will wait until the data can be written. A write ona FIFO that can’t 
accept all of the bytes being written will either: 


Q Fail, if the request is for PIPE_BUF bytes or less and the data can’t be written. 








Q Write part of the data, if the request is for more than PIPE_BUF bytes, returning the number of 
bytes actually written, which could be 0. 


The size of a FIFO is an important consideration. There is a system-imposed limit on how much data can 
be “in” a FIFO at any one time. This is the #define PIPE_BUF, usually found in limits.h. On Linux 
and many other UNIX-like systems, this is commonly 4,096 bytes, but it could be as low as 512 bytes on 
some systems. The system guarantees that writes of PLPE_BUF or fewer bytes on a FIFO that has been 
opened O_WRONLY (that is, blocking) will either write all or none of the bytes. 


Although this limit is not very important in the simple case of a single FIFO writer and a single FIFO 
reader, it’s quite common to use a single FIFO to allow many different programs to send requests to a 
single FIFO reader. If several different programs try to write to the FIFO at the same time, it’s usually 
vital that the blocks of data from different programs don’t get interleaved — that is, each write must 
be “atomic.” How do you do this? 


Well, if you ensure that all your write requests are to a blocking FIFO and are less than PIPE_BUF bytes 
in size, the system will ensure that data never gets interleaved. In general, it’s a good idea to restrict the 
data transferred via a FIFO to blocks of PIPE_BUF bytes, unless you're using only a single-writer and a 
single-reader process. 
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Try It Out Inter-Process Communication with FIFOs 


To show how unrelated processes can communicate using named pipes, you need two separate pro- 
grams, fifo3.cand fifo4.c. 


1. 


The first program is the producer program. It creates the pipe if required, and then writes data 
to it as quickly as possible. 


Note that, for illustration purposes, we don’t mind what the data is, so we don’t bother to initialize a 
buffer. In both listings, shaded lines show the changes from £if02.c, with all the command-line argu- 
ment code removed. 


#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 
#include <fcntl.h> 
#include <limits.h> 
#include <sys/types.h> 
#include <sys/stat.h> 


#define FIFO_NAME "/tmp/my_fifo" 
#define BUFFER_SIZE PIPE_BUF 
#define TEN_MEG (1024 * 1024 * 10) 


int main() 


{ 

















int pipe_fd; 

int res; 

int open_mode = O_WRONLY; 
int bytes_sent = 0; 

char buffer[BUFFER_SIZE + 1]; 


if (access(FIFO_NAME, F_OK) == -1) { 
res = mkfifo(FIFO_NAME, 0777); 
if (res != 0) { 
fprintf(stderr, "Could not create fifo %s\n", FIFO_NAME) ; 
exit (EXIT_FAILURE) ; 








} 


printf("Process %d opening FIFO O_WRONLY\n", getpid()); 
pipe_fd = open(FIFO_NAME, open_mode) ; 
print£("Process %d result %d\n", getpid(), pipe_fd); 


if (pipe_fd != -1) { 
while(bytes_sent < TEN_MEG) { 
res = write(pipe_fd, buffer, BUFFER_SIZE) ; 
Le hres se 7-1) 76 
fprintf(stderr, "Write error on pipe\n"); 
exit (EXIT_FAILURE) ; 
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bytes_sent += res; 
} 
(void) close (pipe_fd) ; 
} 
else { 
exit (EXIT_FAILURE) ; 
} 


printf("Process %d finished\n", getpid()); 
exit (EXIT_SUCCESS) ; 


2. The second program, the consumer, is much simpler. It reads and discards data from the FIFO. 


#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 
#include <fcntl.h> 
#include <limits.h> 
#include <sys/types.h> 
#include <sys/stat.h> 


#define FIFO_NAME "/tmp/my_fifo" 
#define BUFFER_SIZE PIPE_BUF 


int main() 

{ 
int pipe_fd; 
int res; 
int open_mode = O_RDONLY; 
char buffer[BUFFER_SIZE + 1]; 
int bytes_read = 0; 


memset (buffer, '\0', sizeof (buffer) ); 
printf("Process %d opening FIFO O_RDONLY\n", getpid()); 


pipe_fd = open(FIFO_NAME, open_mode) ; 
printf ("Process %d result %d\n", getpid(), pipe_fd); 





Fist (Qos omnia — ae) etl 
do { 
res = read(pipe_fd, buffer, BUFFER_SIZE) ; 
bytes_read += res; 
} while (res > 0); 
(void) close (pipe_fd) ; 





} 
else { 

exit (EXIT_FAILURE) ; 
} 


printf("Process %d finished, %d bytes read\n", getpid(), bytes_read) ; 
exit (EXIT_SUCCESS) ; 
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When you run these programs at the same time, using the time command to time the reader, the output 
you get (with some tidying for clarity) is 


S$ ./£if03 & 

[1] 375 

Process 375 opening FIFO O_WRONLY 

$ time ./fifo4 

Process 377 opening FIFO O_RDONLY 

Process 375 result 3 

Process 377 result 3 

Process 375 finished 

Process 377 finished, 10485760 bytes read 


real Om0.053s 


user Om0.020s 

sys Om0.040s 

[1]+ Done ./£if03 
How It Works 


Both programs use the FIFO in blocking mode. You start £ifo3 (the writer/producer) first, which blocks, 
waiting for a reader to open the FIFO. When £1 £04 (the consumer) is started, the writer is then unblocked 
and starts writing data to the pipe. At the same time, the reader starts reading data from the pipe. 


Linux arranges the scheduling of the two processes so that they both run when they can and are blocked 
when they can’t. Thus, the writer is blocked when the pipe is full, and the reader is blocked when the 


pipe is empty. 


The output from the time command shows that it took the reader well under one-tenth of a second to 
run, reading 10 megabytes of data in the process. This shows that pipes, at least as implemented in modern 
versions of Linux, can be an efficient way of transferring data between programs. 


Advanced Topic: Client/Server Using FIFOs 


For your final look at FIFOs, let’s consider how you might build a very simple client/server application 
using named pipes. You want to have a single-server process that accepts requests, processes them, and 
returns the resulting data to the requesting party: the client. 


You want to allow multiple client processes to send data to the server. In the interests of simplicity, we'll 
assume that the data to be processed can be broken into blocks, each smaller than PIPE_BUF bytes. Of 
course, you could implement this system in many ways, but we'll consider only one method as an illus- 
tration of how named pipes can be used. 


Because the server will process only one block of information at a time, it seems logical to have a single 


FIFO that is read by the server and written to by each of the clients. By opening the FIFO in blocking 
mode, the server and the clients will be automatically blocked as required. 
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Returning the processed data to the clients is slightly more difficult. You need to arrange a second pipe, 
one per client, for the returned data. By passing the process identifier (PID) of the client in the original 
data sent to the server, both parties can use this to generate the unique name for the return pipe. 


Try It Out An Example Client/Server Application 


1. First, you need a header file, client .h, that defines the data common to both client and server 
programs. It also includes the required system headers, for convenience. 


#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 
#include <fcntl.h> 
#include <limits.h> 
#include <sys/types.h> 
#include <sys/stat.h> 


#define SERVER_FIFO_NAM 
#define CLIENT_FIFO_NAM 


"/tmp/serv_fifo" 
"/tmp/cli_%d_fifo" 








EE NE 





#define BUFFER_SIZE 20 


struct data_to_pass_st { 
pidat cle ritmo, 
char some_data[BUFFER_SIZE - 1]; 





Ne 


2. Now for the server program, server .c. In this section, you create and then open the server 
prog y pP 
pipe. It’s set to be read-only, with blocking. After sleeping (for demonstration purposes), the 
server reads in any data from the client, which has the data_to_pass_st structure. 


#include "client.h" 
#include <ctype.h> 


int main() 
( 
ink server fitoutd client_fifo_fd; 
struct data_to_pass_st my_data; 
int read_res; 
char client_fifto[256]; 
char “tmpoctarsper : 


mkfifo(SERVER_FIFO_NAME, 0777); 
server_fifo_fd = open(SERVER_FIFO_NAME, O_RDONLY) ; 
if (server fafo rd ==--1y <4 

fprintf(stderr, "Server fifo failure\n"); 

exit (EXIT_FAILURE) ; 








} 
sleep(10); /* lets clients queue for demo purposes */ 
do { 


read_res = read(server_fifo_fd, &my_data, sizeof (my_data) ); 
if (read_res > 0) { 
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In this next stage, you perform some processing on the data just read from the client: Convert 
all the characters in some_data to uppercase and combine the CLIENT_FIFO_NAME with the 
received client_pid. 





tmp_char_ptr = my_data.some_data; 

while (*tmp_char_ptr) { 
‘tip char ptr = toupper(*tnp char ptr)? 
tmp char pertt; 


} 
sprintf (client_fifo, CLIENT_FIFO_NAME, my_data.client_pid); 


Then send the processed data back, opening the client pipe in write-only, blocking mode. 
Finally, shut down the server FIFO by closing the file and then unlinking the FIFO. 


client_fifo_fd = open(client_fifo, O_WRONLY) ; 

Lf (elient tatoo lid tet 
write(client_fifo_fd, &my_data, sizeof (my_data) ); 
close(client_fifo_fd); 


} 
} while (read_res > 0); 
close(server_fifo_fd); 
unlink (SERVER_FIFO_NAME) ; 
exit (EXIT_SUCCESS) ; 





Here’s the client, client .c. The first part of this program opens the server FIFO, if it already 
exists, as a file. It then gets its own process ID, which forms some of the data that will be sent to 
the server. The client FIFO is created, ready for the next section. 


#include "client.h" 
#include <ctype.h> 


int main() 


{ 


iit Server“ tifo ta: Gbliene Tilia 14? 
struct data_to_pass_st my_data; 

int times_to_send; 

ear claent Ti fol2s6)> 


server_fifo_fd = open(SERVER_FIFO_NAME, O_WRONLY) ; 
te tserver fifo te a= l=) 4 

fprintf(stderr, "Sorry, no server\n"); 

exit (EXIT_FAILURE) ; 





} 


my_data.client_pid = getpid(); 
sprintf (client_fifo, CLIENT_FIFO_NAME, my_data.client_pid); 
Sig (meio (Cllisiye ieico), O77) == =i) 4 
fprintf(stderr, "Sorry, can't make %s\n", client_fifo); 
exit (EXIT_FAILURE) ; 
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6. 


For each of the five loops, the client data is sent to the server. Then the client FIFO is opened 
(read-only, blocking mode) and the data read back. Finally, the server FIFO is closed and the 
client FIFO removed from the file system. 


for 


(times_to_send = 0; 
sprintf (my_data.some_data, 
printf("%d sent %s, 


write(server_fifo_fd, &my_data, 
client_fifo_fd = open(client_fifo, O_RDONLY) ; 


TE 


} 


} 


aie 


} 


close(client_fifo_fd); 


telient Fito. fay vee =1) 
(read(client_fifo_fd, &my_data, 
s\n", my_data.some_data) ; 


printf ("received: 


close(server_fifo_fd); 
unlink(client_fifo) ; 
exit (EXIT_SUCCESS) ; 


times_to_send < 5; 
"Hello from %d", my_data.client_pid); 
"|, my_data.client_pid, my_data.some_data) ; 


times_to_send++) { 


sizeof (my_data) ); 


sizeof (my_data)) > 0) { 


To test this application, you need to run a single copy of the server and several clients. To get them all 
started at close to the same time, use the following shell commands: 


S$ ./server & 


$ for iin1l2345 


do 


-/client & 
done 


$ 


This starts one server process and five client processes. The output from the clients, edited for brevity, 


looks like this: 


531 
532 
529 
530 
531 
532 


sent 
sent 
sent 
sent 
sent 
sent 


Hello 
Hello 
Hello 
Hello 
Hello 
Hello 


from 
from 
from 
from 
from 
from 


531; 
532%, 
529, 
530, 
531, 
532, 


received: 
received: 
received: 
received: 
received: 
received: 





LO 
LO 
LO 
LO 
LO 





LO 


FROM 
FROM 
FROM 
FROM 
FROM 
FROM 


531 
532 
529 
530 
53T 
532 


As you can see in this output, different client requests are being interleaved, but each client is getting 
the suitably processed data returned to it. Note that you may or may not see this interleaving; the order 
in which client requests are received may vary between machines and possibly between runs on the 
same machine. 


How It Works 


Now we'll cover the sequence of client and server operations as they interact, something that we haven’t 


covered so far. 
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The server creates its FIFO in read-only mode and blocks. It does this until the first client connects by open- 
ing the same FIFO for writing. At that point, the server process is unblocked and the sleep is executed, 

so the writes from the clients queue up. (In a real application, the sleep would be removed; we’re only 
using it to demonstrate the correct operation of the program with multiple simultaneous clients.) 


In the meantime, after the client has opened the server FIFO, it creates its own uniquely named FIFO for 
reading data back from the server. Only then does the client write data to the server (blocking if the pipe 
is full or the server’s still sleeping) and then blocks on a read of its own FIFO, waiting for the reply. 


On receiving the data from the client, the server processes it, opens the client pipe for writing, and writes 
the data back, which unblocks the client. When the client is unblocked, it can read from its pipe the data 
written to it by the server. 


The whole process repeats until the last client closes the server pipe, causing the server’s read to fail 
(returning 0) because no process has the server pipe open for writing. If this were a real server process 
that needed to wait for further clients, you would need to modify it to either 

Q Open a file descriptor to its own server pipe, so read always blocks rather than returning 0. 

Q Close and reopen the server pipe when read returns 0 bytes, so the server process blocks in the 


open waiting for a client, just as it did when it first started. 


Both of these techniques are illustrated in the rewrite of the CD database application to use named pipes. 


The CD Database Application 


Now that you’ve seen how you can use named pipes to implement a simple client/server system, you 
can revisit the CD database application and convert it accordingly. You'll also incorporate some signal 
handling to allow you to perform some tidy-up actions when the process is interrupted. You will use the 
earlier dbm version of the application that had a command-line interface to see the code as straightfor- 
wardly as possible. 


Before you get to look in detail at this new version, you must compile the application. If you have the 
source code from the website, use the makefile to compile it into the server and client programs. 


As you saw early in Chapter 7, different distributions name and install the dbm files in slightly differ- 
ent ways. If the provided files do not compile on your distribution, check back to Chapter 7 for further 
advice on the naming and location of the dbm files. 


Running server -i allows the program to initialize a new CD database. 


Needless to say, the client won’t run unless the server is up and running. Here’s the makefile to show 
how the programs fit together: 


aise server client 


553 


Chapter 13: Inter-Process Communication: Pipes 


CC=cc 
CFLAGS= -pedantic -Wall 


# For debugging un-comment the next line 

# DFLAGS=-DDEBUG_TRACE=1 -g 

# Where, and which version, of dbm are we using. 

# This assumes gdbm is pre-installed in a standard place, but we are 

# going to use the gdbm compatibility routines, that make it emulate ndbm. 
# We do this because ndbm is the 'most standard' of the dbm versions. 

# Depending on your distribution, these may need changing. 


DBM_INC_PATH=/usr/include/gdbm 

DBM_LIB_PATH=/usr/lib 

DBM_LIB_FILE=-lgdbm 

# On some distributions you may need to change the above line to include 
# the compatibility library, as shown below. 

# DBM_LIB_FILE=-lgdbm_compat -lgdbm 








-C.0: 
$(CC) $(CFLAGS) -I$(DBM_INC_PATH) $(DFLAGS) -c $< 


app_ui.o: app_ui.c cd_data.h 

cd_dbm.o: cd_dbm.c cd_data.h 

client_f.o: clientif.c cd_data.h cliserv.h 
pipe_imp.o: pipe_imp.c cd_data.h cliserv.h 
server.o: server.c cd_data.h cliserv.h 


client: app_ui.o clientif.o pipe_imp.o 
$(CC) -o client $(DFLAGS) app_ui.o clientif.o pipe_imp.o 


server: server.o cd_dbm.o pipe_imp.o 
$(CC) -o server -L$(DBM_LIB_ PATH) $(DFLAGS) server.o cd_dbm.o pipe_imp.o - 
1$ (DBM_LIB_FILE) 


clean: 
rm -f£ server client_app *.o *~ 


Aims 


The aim is to split the part of the application that deals with the database away from the user inter- 
face part of the application. You also want to run a single-server process, but allow many simultane- 
ous clients, and to minimize changes to the existing code. Wherever possible, you will leave existing 


code unchanged. 


To keep things simple, you also want to be able to create (and delete) pipes within the application, so 


there’s no need for a system administrator to create named pipes before you can use them. 


It’s also important to ensure that you never “busy wait,” wasting CPU time, for an event. As you’ve 
seen, Linux allows you to block, waiting for events without using significant resources. You should use 
the blocking nature of pipes to ensure that you use the CPU efficiently. After all, the server could, in the- 


ory, wait for many hours for a request to arrive. 
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Implementation 


The earlier, single-process version of the application that you saw in Chapter 7 used a set of data access 
routines for manipulating the data. These were 


int database_initialize(const int new_database) ; 
void database_close(void) ; 
cdc_entry get_cdc_entry(const char *cd_catalog_ptr) ; 
cdt_entry get_cdt_entry(const char *cd_catalog_ptr, const int track_no); 
int add_cdc_entry(const cdc_entry entry_to_add) ; 
int add_cdt_entry(const cdt_entry entry_to_add) ; 
int del_cdc_entry(const char *cd_catalog_ptr) ; 
int del_cdt_entry(const char *cd_catalog_ptr, const int track_no); 
cdc_entry search_cdc_entry(const char *cd_catalog_ptr, 
Tae Sirat CALL gerip 


These functions provide a convenient place to make a clean separation between client and server. 


In the single-process implementation, you can view the application as having two parts, even though it 
was compiled as a single program, as shown in Figure 13-6. 





Data access 
routines 
































User Interface Database access 











Figure 13-6 


In the client-server implementation, you want to insert some named pipes and supporting code between 
the two major parts of the application. Figure 13-7 shows the structure you need. 


In the implementation, both the client and server interface routines are put in the same file, pipe_imp. c. 
This keeps all the code that depends on the use of named pipes for the client/server implementation in a 
single file. The formatting and packaging of the data being passed is kept separate from the routines that 
implement the named pipes. You end up with more source files, but a better logical division between 
them. The calling structure in the application is illustrated in Figure 13-8. 


The files app_ui.c, client_if.c,and pipe_imp.c are compiled and linked together to give a client pro- 
gram. The files cd_dbm.c, server .c, and pipe_imp.c are compiled and linked together to give a server 
program. A header file, cliserv.h, acts as a common definitions header file to tie the two together. 


The files app_ui.c and cd_dbm.c have only very minor changes, principally to allow for the split into two 


programs. Because the application is now quite large and a significant proportion of the code is unchanged 
from that previously seen, we show here only the files cliserv.h, client_if.c,and pipe_imp.c. 
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Some parts of this file are dependent on the specific client/server implementation, in this case named 
pipes. We'll be changing to a different client/server model at the end of Chapter 14. 
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Figure 13-7 
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The Header File, cliserv.h 


First look at cliserv.h. This file defines the client/server interface. It’s required by both client and 
server implementations. 


1. Following are the required #include headers: 


#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <fcntl.h> 
#include <limits.h> 
#include <sys/types.h> 
#include <sys/stat.h> 


2. You then define the named pipes. Use one pipe for the server and one pipe for each client. 
Because there may be multiple clients, the client incorporates a process ID into the name to 
ensure that its pipe is unique: 


#define SERVER_PIPE "/tmp/server_pipe" 
#define CLIENT_PIPE "/tmp/client_%d_pipe" 








#define ERR_TEXT_LEN 80 
3. Implement the commands as enumerated types, rather than #defines. 


This is a good way of allowing the compiler to do more type checking and also helps in debugging the 
application, because many debuggers are able to show the name of enumerated constants, but not 
the name defined by a #define directive. 


The first typedef gives the type of request being sent to the server; the second gives the server 
response to the client: 


typedef enum { 
s_create_new_database = 0, 
s_get_cdc_entry, 
s_get_cdt_entry, 
s_add_cdc_entry, 
s_add_cdt_entry, 
s_del_cdc_entry, 
s_del_cdt_entry, 
s_find_cdc_entry 

} client_request_e; 


typedef enum { 
r_success = 0, 
r_failure, 
r_find_no_more 

} server_response_e; 
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4. Next, declare a structure that will form the message passed in both directions between the 
two processes. 


Because you don’t actually need to return both a cdc_entry and cdt_entry in the same response, 
you could have combined them in a union. However, for simplicity you can keep them separate. This 


also makes the code easier to maintain. 


typedef struct { 


pridig client_pid; 

client_request_e request; 

server_response_e response; 

cdc_entry cdc_entry_data; 

cdt_entry cdt_entry_data; 

char error_text [ERR_TEXT_LEN + 1]; 





} message_db_t; 


5. Finally, here are the pipe interface functions that perform data transfer, implemented in 
pipe_imp.c. These divide into server- and client-side functions, in the first and second 
blocks, respectively: 


int server_starting (void); 

void server_ending (void); 

int read_request_from_client (message_db_t *rec_ptr); 

int start_resp_to_client (const message_db_t mess_to_send); 
int send_resp_to_client (const message_db_t mess_to_send); 
void end_resp_to_client (void); 


int client_starting (void); 

void client_ending (void); 

int send_mess_to_server (message_db_t mess_to_send); 
int start_resp_from_server (void); 

int read_resp_from_server (message_db_t *rec_ptr); 
void end_resp_from_server (void); 


We split the rest of the discussion into the client interface functions and details of the server- and client- 
side functions found in pipe_imp. c, and we look at the source code as necessary. 


Client Interface Functions 


Now look at clientif.c. This provides “fake” versions of the database access routines. These encode the 
request in a message_db_t structure and then use the routines in pipe_imp.c to transfer the request to 
the server. This allows you to make minimal changes to the original app_ui.c. 


The Client’s Interpreter 


1. This file implements the nine database functions prototyped in cd_data .h. It does so by pass- 
ing requests to the server and then returning the server response from the function, acting as an 
intermediary. The file starts with #include files and constants: 


#define _POSIX_SOURCE 
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#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <fcntl.h> 


#include <limits.h> 
#include <sys/types.h> 
#include <sys/stat.h> 


#include "cd_data.h" 
#include "cliserv.h" 


The static variable mypid reduces the number of calls to getpid that would otherwise be 
required. We use a local function, read_one_response, to eliminate duplicated code: 


static pid_t mypid; 


static int read_one_response(message_db_t *rec_ptr); 


3. 


The database_initialize and close routines are still called, but are now used, respectively, 
for initializing the client side of the pipes interface and for removing redundant named pipes 


when the client exits: 


int database_initialize(const int new_database) 


{ 


} 


if (!client_starting()) return(0); 
mypid = getpid(); 
return(1); 


/* database_initialize */ 


void database_close(void) { 


4. 


client_ending() ; 


The get_cdc_entry routine is called to get a catalog entry from the database, given a CD cata- 
log title. Here you encode the request in a message_db_t structure and pass it to the server. You 
then read the response back into a different message_db_t structure. If an entry is found, it’s 
included inside the message_db_t structure as a cdc_entry structure, so you pass back the 


appropriate part of the structure: 


cdc_entry get_cdc_entry(const char *cd_catalog_ptr) 


{ 


cdc_entry ret_val; 
message_db_t mess_send; 
message_db_t mess_ret; 


ret_val.catalog[0] = '\0'; 
mess_send.client_pid = mypid; 
mess_send.request = s_get_cdc_entry; 


strcpy (mess_send.cdc_entry_data.catalog, cd_catalog_ptr); 


if (send_mess_to_server (mess_send) ) 


{ 
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if (read_one_response(&mess_ret)) { 


if (mess_ret.response == r_success) { 
ret_val = mess_ret.cdc_entry_data; 
} else { 


fprintf(stderr, "%s", mess_ret.error_text) ; 
} 
} else { 
fprintf(stderr, "Server failed to respond\n") ; 
} 
} else { 
fprintf(stderr, "Server not accepting requests\n") ; 
} 


return (ret_val); 


5. Here’s the source for the function read_one_response that you use to avoid duplicating code: 
static int read_one_response (message_db_t *rec_ptr) { 


int return_code = 0; 
if (!rec_ptr) return(0); 


if (start_resp_from_server()) { 
if (read_resp_from_server(rec_ptr)) { 
return_code = 1; 
} 
end_resp_from_server () ; 
} 


return (return_code) ; 


6. The other get_xxx, del_xxx, and add_xxx routines are implemented in a similar way to the 
get_cdc_entry function and are reproduced here for completeness. First, the function for 
retrieving CD tracks: 


cdt_entry get_cdt_entry(const char *cd_catalog_ptr, const int track_no) 
{ 

cdt_entry ret_val; 

message_db_t mess_send; 

message_db_t mess_ret; 


ret_val.catalog[0] = '\0'; 

mess_send.client_pid = mypid; 

mess_send.request = s_get_cdt_entry; 
strcpy(mess_send.cdt_entry_data.catalog, cd_catalog_ptr) ; 
mess_send.cdt_entry_data.track_no = track_no; 


if (send_mess_to_server(mess_send)) { 
if (read_one_response(&mess_ret)) { 


if (mess_ret.response == r_success) { 
ret_val = mess_ret.cdt_entry_data; 
} else { 


fprintf(stderr, "%s", mess_ret.error_text) ; 
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i 
} else { 
fprintf(stderr, "Server failed to respond\n"); 
} 
} else { 


fprintf (stderr, "Server not accepting requests\n"); 
} 


return (ret_val); 


T. Next, two functions for adding data, first to the catalog and then to the tracks database: 


int add_cdc_entry(const cdc_entry entry_to_add) 


{ 
message_db_t mess_send; 
message_db_t mess_ret; 
mess_send.client_pid = mypid; 
mess_send.request = s_add_cdc_entry; 
mess_send.cdc_entry_data = entry_to_add; 
if (send_mess_to_server(mess_send)) { 
if (read_one_response(&mess_ret)) { 
if (mess_ret.response == r_success) { 
return(1); 
} else { 
fprintf(stderr, "3s", mess_ret.error_text); 
} 
} else { 
fprintf(stderr, "Server failed to respond\n") ; 
} 
} else { 
fprintf(stderr, "Server not accepting requests\n"); 
} 
return (0); 
} 


int add_cdt_entry(const cdt_entry entry_to_add) 
{ 

message_db_t mess_send; 

message_db_t mess_ret; 


mess_send.client_pid = mypid; 
mess_send.request = s_add_cdt_entry; 
mess_send.cdt_entry_data = entry_to_add; 


if (send_mess_to_server(mess_send)) { 
if (read_one_response(&mess_ret)) { 


if (mess_ret.response == r_success) { 
return(1); 
} else { 
fprintf(stderr, "3s", mess_ret.error_text); 
} 
} else { 
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fprintf(stderr, "Server failed to respond\n") ; 
} 
} else { 
fprintf(stderr, "Server not accepting requests\n") ; 
} 
return (0); 


8. Last, two functions for data deletion: 


int del_cdc_entry(const char *cd_catalog_ptr) 
{ 

message_db_t mess_send; 

message_db_t mess_ret; 


mess_send.client_pid = mypid; 
mess_send.request = s_del_cdc_entry; 
strcpy (mess_send.cdc_entry_data.catalog, cd_catalog_ptr); 


if (send_mess_to_server(mess_send)) { 
if (read_one_response(&mess_ret)) { 


if (mess_ret.response == r_success) { 
return(1); 
} else { 


fprintf(stderr, "%s", mess_ret.error_text) ; 
} 
} else { 
fprintf(stderr, "Server failed to respond\n") ; 
} 
} else { 
fprintf(stderr, "Server not accepting requests\n") ; 
} 


return (0); 


int del_cdt_entry(const char *cd_catalog_ptr, const int track_no) 


message_db_t mess_send; 
message_db_t mess_ret; 


mess_send.client_pid = mypid; 

mess_send.request = s_del_cdt_entry; 

strcpy (mess_send.cdt_entry_data.catalog, cd_catalog_ptr) ; 
mess_send.cdt_entry_data.track_no = track_no; 


if (send_mess_to_server(mess_send)) { 
if (read_one_response(&mess_ret)) { 


if (mess_ret.response == r_success) { 
return(1); 
} else { 


fprintf(stderr, "%s", mess_ret.error_text) ; 


} 
} else { 
fprintf(stderr, "Server failed to respond\n") ; 
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} else { 
fprintf(stderr, "Server not accepting requests\n") ; 
} 


return (0); 


Searching the Database 


The function for the search on the CD key is more complex. The user of this function expects to call it 
once to start a search. We catered to this expectation in Chapter 7 by setting *first_call_ptr to true 
on this first call and the function then to return the first match. On subsequent calls to the search func- 
tion, *first_call_ptr is false and further matches are returned, one per call. 


Now that you've split the application across two processes, you can no longer allow the search to proceed 
one entry at a time in the server, because a different client may request a different search from the server 
while your search is in progress. You can’t make the server side store the context (how far the search has 
gotten) for each client search separately, because the client side can simply stop searching part of the way 
through a search, when a user finds the CD he is looking for or if the client “falls over.” 


You can either change the way the search is performed or, as in the following code, hide the complexity 
in the interface routine. This code arranges for the server to return all the possible matches to a search 
and then store them in a temporary file until the client requests them. 


1. This function looks more complicated than it is because it calls three pipe functions that you'll 
be looking at in the next section: send_mess_to_server, start_resp_from_server, and 
read_resp_from_server. 


cdc_entry search_cdc_entry(const char *cd_catalog_ptr, int *first_call_ptr) 
{ 

message_db_t mess_send; 

message_db_t mess_ret; 





Static FILE *work_file = (FIDE *).0; 
static int entries_matching = 0; 
cdc_entry ret_val; 


ret_val.catalog[0] = '\0'; 


if (!work_file && (*first_call_ptr == 0)) return(ret_val); 


2. Here's the first call to search, that is, with *first_call_ptr set to true. It’s set to false 
immediately, in case you forget. A work_file is created and the client message structure initial- 
ized. 


AA ES CECR ET { 
Ambr S PECAN EPEn ERO 
if (work_file) fclose(work_file); 
work_file = tmpfile(); 
if (!work_file) return(ret_val) ; 


mess_send.client_pid = mypid; 


mess_send.request = s_find_cdc_entry; 
strcpy (mess_send.cdc_entry_data.catalog, cd_catalog_ptr); 
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3. Next, there’s this three-deep condition test, which makes calls to functions in pipe_imp.c. If 
the message is successfully sent to the server, the client waits for the server’s response. While 
reads from the server are successful, the search matches are returned to the client’s work_file 
and the entries_matching counter is incremented. 


if (send_mess_to_server(mess_send)) { 


if (start_resp_from_server()) { 
while (read_resp_from_server(&mess_ret)) { 
if (mess_ret.response == r_success) { 


fwrite(&mess_ret.cdc_entry_data, sizeof(cdc_entry), 1, work_file); 
entries_matching++; 
} else { 
break; 
} 
} /* while */ 
} else { 
fprintf(stderr, "Server not responding\n") ; 
} 
} else { 
fprintf(stderr, "Server not accepting requests\n"); 


4. The next test checks whether the search had any luck. Then the fseek call sets the work_file 
to the next place for data to be written. 


if (entries_matching == 0) { 
fclose(work_file); 
work file = (FILE *)0; 


return (ret_val) ; 


} 
(void) fseek(work_file, OL, SEEK_SET); 


5. If this is not the first call to the search function with this particular search term, the code checks 
whether there are any matches left. Finally, the next matching entry is read to the ret_val 
structure. The previous checks guarantee that a matching entry exists. 


} else { 
oE e eee ee o 
if (entries_matching == 0) { 
fclose(work_file); 
Work.iile a]. (F ILE *) 0s 


return (ret_val) ; 


fread(&ret_val, sizeof(cdc_entry), 1, work_file); 
entries_matching--; 


return (ret_val) ; 
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The Server Interface, server.c 


Just as the client side has an interface to the app_ui.c program, so the server side needs a program to 
control the (renamed) cd_access.c, now cd_dbm.c. The server’s main function is listed here. 


1. 


Start by declaring some global variables, a prototype for the process_command function, and a 


signal-catcher function to ensure a clean exit: 


#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <fcntl.h> 
#include <limits.h> 
#include <signal.h> 
#include <string.h> 
#include <errno.h> 
#include <sys/types.h> 
#include <sys/stat.h> 


#include "cd_data.h" 
#include "cliserv.h" 


int save_errno; 
static int server_running = 1; 


static void process_command(const message_db_t mess_command) ; 


void catch_signals() 


{ 


int 


server_running = 0; 


Now you come to the main function. After checking that the signal-catching routines are all 
right, the program checks to see whether you passed -i on the command line. If you did, it will 
create a new database. If the call to the database_initialize routine in cd_dbm.c fails, an 
error message is shown. If all is well and the server is running, any requests from the client are 
fed to the process_command function, which you'll see in a moment. 


main(int argc, char *argv[]) { 

struct sigaction new_action, old_action; 
message_db_t mess_command; 

int database_init_type = 0; 


new_action.sa_handler = catch_signals; 
sigemptyset (&new_action.sa_mask) ; 
new_action.sa_flags = 0; 


if ((sigaction(SIGINT, &new_action, &o0ld_action) != 0) || 
(sigaction(SIGHUP, &new_action, &old_action) != 0) || 
(sigaction(SIGTERM, &new_action, &old_action) != 0)) 


{ 


fprintf (stderr, "Server startup error, signal catching failed\n"); 





exit (EXIT_FAILURE) ; 
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mit (ace = i) 4 
argvt+t+; 
if (strnemp("-i", *argv, 2) == 0) database_init_type = 1; 
} 
if (!database_initialize(database_init_type)) { 
fprintf(stderr, "Server error:-\ 
could not initialize database\n"); 
exit (EXIT_FAILURE) ; 





if (!server_starting()) exit (EXIT_FAILURE) ; 





while(server_running) { 
if (read_request_from_client (&mess_command)) { 
process_command(mess_command) ; 
} else { 
if(server_running) fprintf(stderr, "Server ended - can not \ 
read pipe\n"); 
server_running = 0; 
} 
} /* while */ 
server_ending(); 
exit (EXIT_SUCCESS) ; 


Any client messages are fed to the process_command function, where they are fed into a case 
statement that makes the appropriate calls to cd_dbm.c: 


static void process_command(const message_db_t comm) 


{ 


message_db_t resp; 
iit Errat timers: 1s 


resp = comm; /* copy command back, then change resp as required */ 


if (!start_resp_to_client(resp)) { 
fprintf(stderr, "Server Warning: -\ 
start_resp_to_client %d failed\n", resp.client_pid); 
return; 


resp.response = r_success; 
memset (resp.error_text, '\0', sizeof(resp.error_text) ); 
save_errno = 0; 


switch(resp.request) { 

case s_create_new_database: 
if (!database_initialize(1)) resp.response = r_failure; 
break; 

case s_get_cdc_entry: 
resp.cdc_entry_data = 

get_cdc_entry(comm.cdc_entry_data.catalog) ; 

break; 

case s_get_cdt_entry: 
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resp.cdt_entry_data = 
get_cdt_entry(comm.cdt_entry_data.catalog, 
comm.cdt_entry_data.track_no) ; 
break; 
case s_add_cdc_entry: 
if (!add_cdc_entry(comm.cdc_entry_data)) resp.response 
r_failure; 


break; 
case s_add_cdt_entry: 
if (!add_cdt_entry(comm.cdt_entry_data)) resp.response = 
r_failure; 
break; 
case s_del_cdc_entry: 
if (!del_cdc_entry(comm.cdc_entry_data.catalog)) resp.response 
= refavlure; 
break; 
case s_del_cdt_entry: 
if (!del_cdt_entry(comm.cdt_entry_data.catalog, 
comm.cdt_entry_data.track_no)) resp.response = r_failure; 
break; 
case s_find_cdc_entry: 
cla if 
resp.cdc_entry_data = 
search_cdc_entry(comm.cdc_entry_data.catalog, 
&first_time) ; 
if (resp.cdc_entry_data.catalog[0] != 0) { 
resp.response = r_success; 
if (!send_resp_to_client(resp)) { 
fprintf(stderr, "Server Warning:-\ 
failed to respond to %d\n", resp.client_pid) ; 


break; 
} 
} else { 
resp.response = r_find_no_more; 
} 
} while (resp.response == r_success); 
break; 
default: 
resp.response = r_failure; 
break; 


D E ERE 


sprintf (resp.error_text, "Command failed:\n\t%s\n", 
strerror (save_errno)); 


if (!send_resp_to_client(resp)) { 


fprintf(stderr, "Server Warning:-\ 
failed to respond to %d\n", resp.client_pid) ; 


end_resp_to_client(); 
TOCOrIS 
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Before you look at the actual pipe implementation, let’s discuss the sequence of events that needs to 
occur to pass data between the client and server processes. Figure 13-9 shows both client and server 
processes starting and how both parties loop while processing commands and responses. 
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Figure 13-9 


In this implementation, the situation is slightly more difficult, because, for a search request, the client 
passes a single command to the server and then expects to receive one or more responses from the 
server. This leads to some additional complexity, mainly in the client. 
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The Pipe 


Here’s the pipes implementation file, pipe_imp.c, which has both the client- and server-side functions. 


As you saw in Chapter 10, the symbol DEBUG_TRACE can be defined to show the sequence of calls as 
the client and server processes pass messages to each other. 


Pipes Implementation Header 
1. First the #includes: 


#include "cd_data.h" 
#include "cliserv.h" 


2. You also define some values that you need in different functions within the file: 


static int server_fd = -1; 

Siecle ke PICEO 

static char client_pipe_name[PATH_MAX + 1] = {'\0'}; 
static int client fd = -15 

static int client_write_fd = -1; 


Server-Side Functions 


Next, you need to look at the server-side functions. The next section shows the functions that open and 
close the named pipe and read messages from the clients. The following section shows the code that 
opens, sends, and closes the client pipes based on the process ID the client includes in its message. 


Server Functions 


{. The server_starting routine creates the named pipe from which the server will read com- 
mands. It then opens that pipe for reading. This open will block until a client opens the pipe for 
writing. Use a blocking mode so that the server can perform blocking reads on the pipe while 
waiting for commands to be sent to it. 


int server_starting (void) 


#if£ DEBUG_TRACE 
printf("%d :- server_starting()\n", getpid()); 
#endif 





unlink (SERVER_PIPE) ; 
if (mkfifo(SERVER_PIPE, 0777) == -1) { 














fprintf(stderr, "Server startup error, no FIFO created\n"); 
return (0) ; 

} 

if ((server_fd = open(SERVER_PIPE, O_RDONLY)) == -1) { 
if (errno == EINTR) return(0); 
fprintf(stderr, "Server startup error, no FIFO opened\n"); 
return (0); 

} 

return (1); 
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2. When the server ends, it removes the named pipe so that clients can detect that no server 
is running: 


void server_ending (void) 
{ 
#i£ DEBUG_TRACE 
printf("%d :- server_ending()\n", getpid()); 
#endif 


(void) close(server_fd) ; 
(void) unlink (SERVER_PIPE) 





3. The read_request_from_client function shown in the following example will block reading 
in the server pipe until a client writes a message into it: 


int read_request_from_client (message_db_t *rec_ptr) 
{ 

int return_code = 0; 

int read_bytes; 


#if DEBUG_TRACE 


printf ("%d :- read_request_from_client()\n", getpid()); 
#endif 


if (server_fd != -1) { 
read_bytes = read(server_fd, rec_ptr, sizeof(*rec_ptr)); 


} 


return (return_code) ; 


In the special case where no clients have the pipe open for writing, the read will return 0; that 
is, it detects an EOF. Then the server closes the pipe and opens it again, so that it blocks until a 
client also opens the pipe. This is just the same as when the server first starts; you have reinitial- 
ized the server. Insert this code into the preceding function: 





if (read_bytes == 0) { 
(void) close(server_fd) ; 
if ((server_fd = open(SERVER_PIPE, O_RDONLY)) == -1) { 
if (errno != EINTR) { 


fprintf(stderr, "Server error, FIFO open failed\n"); 
} 
return (0) ; 


} 


read_bytes = read(server_fd, rec_ptr, sizeof(*rec_ptr)); 
} 


if (read_bytes == sizeof(*rec_ptr)) return_code = 1; 
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The server is a single process that may be serving many clients simultaneously. Because each client uses 
a different pipe to receive its responses, the server needs to write to a different pipe to send responses to 
different clients. Because file descriptors are a limited resource, the server opens a client pipe for writing 
only when it has data to send. 


The code splits the opening, writing, and closing of the client pipe into three separate functions. You 
need to do this when you're returning multiple results to a search, so you can open the pipe once, write 
many responses, and close it again. 


Plumbing the Pipes 
1. 


int 


{ 


int 


3. 


First open the client pipe: 


start_resp_to_client (const message_db_t mess_to_send) 


#if DEBUG_TRACE 
printf("%d :- start_resp_to_client()\n", getpid()); 
#endif 








(void) sprintf (client_pipe_name, CLIENT_PIPE, mess_to_send.client_pid) ; 
if ((client_fd = open(client_pipe_name, O_WRONLY)) == -1) return(0); 
return(1); 


The messages are all sent using calls to this function. You'll see the corresponding client-side 
functions that field the message later. 


send_resp_to_client (const message_db_t mess_to_send) 
int write_bytes; 


#if DEBUG_TRACE 
printf("%d :- send_resp_to_client()\n", getpid()); 





#endif 

Ve (cltent fd-s= -1L) return(0) + 

write_bytes = write(client_fd, &mess_to_send, sizeof (mess_to_send) ); 
if (write_bytes != sizeof(mess_to_send)) return(0); 

return(1); 


Finally, close the client pipe: 


void end_resp_to_client (void) 


{ 


#if£ DEBUG_TRACE 
printf("%d :- end_resp_to_client()\n", getpid()); 
#endif 





sie (eilaieinje seel Y= <i) 4 
(void) close(client_fd) ; 
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client. fad = cI; 


Client-Side Functions 


Complementing the server are the client functions in pipe_imp.c. They are very similar to the server- 
side functions, except for the worryingly named send_mess_to_server function. 


Client Functions 


1. After checking that a server is accessible, the client _starting function initializes the client- 
side pipe: 


int client_starting (void) 
#i1£ DEBUG_TRACE 
printf("td :- client_starting\n", getpid()); 


#endif 


mypid = getpid(); 





if ((server_fd = open(SERVER_PIPE, O_WRONLY)) == -1) { 
fprintf(stderr, "Server not running\n"); 
return (0) ; 


} 


(void) sprintf (client_pipe_ name, CLIENT_PIPE, mypid); 
(void) unlink (client_pipe_name) ; 
if (mkfifo(client_pipe_name, 0777) == -1) { 
fprintf(stderr, "Unable to create client pipe %s\n", 
client_pipe_name) ; 
return (0) ; 





} 


return(1); 


2.  Theclient_ending function closes file descriptors and deletes the now-redundant named pipe: 


void client_ending (void) 
{ 
#i1£ DEBUG_TRACE 
printf("%d :- client_ending()\n", getpid()); 


#endif 

if (client_write_fd != -1) (void)close(client_write_fd) ; 
if (client_fd != -1) (void)close(client_fd) ; 

if (server_fd != -1) (void)close(server_fd); 


(void) unlink (client_pipe_name) ; 


3.  Thesend_mess_to_server function passes the request through the server pipe: 


int send_mess_to_server(message_db_t mess_to_send) 
{ 
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int write_bytes; 


#if DEBUG_TRACE 

printf("%d :- send_mess_to_server()\n", getpid()); 
#endif 
if (server_fd == -1) return (0)? 
mess_to_send.client_pid = mypid; 





write_bytes = write(server_fd, &mess_to_send, sizeof (mess_to_send) ); 
if (write_bytes != sizeof(mess_to_send)) return(0); 
return(1); 


As with the server-side functions you saw earlier, the client gets results back from the server using three 
functions, to cater to multiple search results. 


Getting Server Results 
1. 


int 


2. 


int 


This client function starts to listen for the server response. It opens a client pipe as read-only 
and then reopens this pipe’s file as write-only. You'll see why a bit later in the section. 





start_resp_from_server (void) 
#if DEBUG_TRACE 
printf ("%d :- start_resp_from_server()\n", getpid()); 
#endif 
if (client_pipe_name[0] == '\0') return(0); 
Tt (client: fd IEA recura) 


client_fd = open(client_pipe_name, O_RDONLY) ; 


age (ellaieiate_azel Ha il) 4 
client_write_fd = open(client_pipe_ name, O_WRONLY) ; 
if (client_write_fd != -1) return(1); 


(void) close(client_fd) ; 
Gilaieyaye eel = =ile 
} 


return (0); 


Here’s the main read from the server that gets the matching database entries: 


read_resp_from_server (message_db_t *rec_ptr) 


int read_bytes; 
int return_code = 0; 





#if DEBUG_TRACE 
printf("%d :- read_resp_from_server()\n", getpid()); 
#endif 


if (!rec_ptr) return(0) ; 
if (client fd == =1) return (0) 


read_bytes = read(client_fd, rec_ptr, sizeof(*rec_ptr)); 
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if (read_bytes == sizeof(*rec_ptr)) return_code = 1; 
return (return_code) ; 


3. And finally, here’s the client function that marks the end of the server response: 


void end_resp_from_server (void) 
{ 
#i1£ DEBUG_TRACE 
printf("%d :- end_resp_from_server()\n", getpid()); 
#endif 


/* This function is empty in the pipe implementation */ 


The second, additional open of the client pipe for writing in start_resp_from_server, 
client_write_fd = open(client_pipe_name, O_WRONLY) ; 


is used to prevent a race condition when the server needs to respond to several requests from the client 
in quick succession. 


To explain this a little more, consider the following sequence of events: 


1. The client writes a request to the server. 


2. The server reads the request, opens the client pipe, and sends the response back, but is sus- 
pended before it gets as far as closing the client pipe. 


3. The client opens its pipe for reading, reads the first response, and closes its pipe. 
4. The client then sends a new command and opens the client pipe for reading. 
5. The server then resumes running, closing its end of the client pipe. 


Unfortunately, at this point the client is trying to read the pipe, looking for a response to its next request, 
but the read will return with 0 bytes because no process has the client pipe open for writing. 


By allowing the client to open its pipe for both reading and writing, thus removing the need for repeat- 
edly reopening the pipe, you avoid this race condition. Note that the client never writes to the pipe, so 
there’s no danger of reading erroneous data. 


Application Summary 


You’ve now separated the CD database application into a client and a server, enabling you to develop the 
user interface and the underlying database technology independently. You can see that a well-defined data- 
base interface allows each major element of the application to make the best use of computer resources. If 
you took things a little further, you could change the pipes implementation to a networked one and use a 
dedicated database server machine. You learn more about networking in Chapter 15. 
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Summary 


In this chapter, you looked at passing data between processes using pipes. First, you looked at unnamed 
pipes, created with the popen or the pipe call, and saw how, using a pipe and the dup call, you can pass 
data from one program to the standard input of another. You then looked at named pipes and showed 
how you can pass data between unrelated programs. Finally, you implemented a simple client/server 
example, using FIFOs to provide not only for process synchronization, but also bidirectional data flow. 
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Semaphores, Shared 
Memory, and Message 
Queues 


In this chapter, we discuss a set of inter-process communication facilities that were originally 
introduced in the AT&T System V.2 release of UNIX. Because all these facilities appeared in the 
same release and have a similar programmatic interface, they are often referred to as the IPC 
(Inter-Process Communication) facilities, or more commonly System V IPC. As you’ve already 
seen, they are by no means the only way of communicating between processes, but the expression 
System V IPC is usually used to refer to these specific facilities. 


We cover the following topics in this chapter: 


OQ Semaphores, for managing access to resources 


Q Shared memory, for highly efficient data sharing between programs 





O Messaging, for an easy way of passing data between programs 


Semaphores 


When you write programs that use threads operating in multiuser systems, multiprocessing sys- 
tems, or a combination of the two, you may often discover that you have critical sections of code, 
where you need to ensure that a single process (or a single thread of execution) has exclusive 
access to a resource. 


Semaphores have a complex programming interface. Fortunately, you can easily provide a much- 
simplified interface that is sufficient for most semaphore-programming problems. 


In the first example application in Chapter 7 — using dbm to access a database — the data could 
be corrupted if multiple programs tried to update the database at exactly the same time. There’s 
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no trouble with two different programs asking different users to enter data for the database; the only 
potential problem is in the parts of the code that update the database. These sections of code, which 
actually perform data updates and need to execute exclusively, are called critical sections. Frequently they 
are just a few lines of code from much larger programs. 


To prevent problems caused by more than one program simultaneously accessing a shared resource, you 
need a way of generating and using a token that grants access to only one thread of execution in a criti- 
cal section at a time. You saw briefly in Chapter 12 some thread-specific ways you could use a mutex or 
semaphores to control access to critical sections in a threaded program. In this chapter, we return to the 
topic of semaphores, but look more generally at how they are used between different processes. 


The semaphore functions used with threads that you saw in Chapter 12 are not the more general ones 
we discuss in this chapter, so be careful not to confuse the two types. 


It’s surprisingly difficult to write general-purpose code that ensures that one program has exclusive 
access to a particular resource, although there’s a solution known as Dekker’s Algorithm. Unfortunately, 
this algorithm relies on a “busy wait,” or “spin lock,” where a process runs continuously, waiting for a 
memory location to be changed. In a multitasking environment such as Linux, this is an undesirable 
waste of CPU resources. The situation is much easier if hardware support, generally in the form of spe- 
cific CPU instructions, is available to support exclusive access. An example of hardware support would 
be an instruction to access and increment a register in an atomic way, such that no other instruction (not 
even an interrupt) could occur between the read/increment/write operations. 


One possible solution that you’ve already seen is to create files using the O_EXCL flag with the open func- 
tion, which provides atomic file creation. This allows a single process to succeed in obtaining a token: the 
newly created file. This method is fine for simple problems, but rather messy and very inefficient for more 
complex examples. 


An important step forward in this area of concurrent programming occurred when Edsger Dijkstra, a 
Dutch computer scientist, introduced the concept of the semaphore. As briefly mentioned in Chapter 12, 
a semaphore is a special variable that takes only whole positive numbers and upon which programs can 
only act atomically. In this chapter we expand on that earlier simplified definition. We show in more 
detail how semaphores function, and how the more general-purpose functions can be used between 
separate processes, rather than the special case of multi-threaded programs you saw in Chapter 12. 


A more formal definition of a semaphore is a special variable on which only two operations are allowed; 
these operations are officially termed wait and signal. Because “wait” and “signal” already have special 


meanings in Linux programming, we'll use the original notation: 


a P (semaphore variable) for wait 





Q v(semaphore variable) for signal 


These letters come from the Dutch words for wait (passeren: to pass, as in a checkpoint before the critical 
section) and signal (vrijgeven: to give or release, as in giving up control of the critical section). You may 
also come across the terms “up” and “down” used in relation to semaphores, taken from the use of sig- 
naling flags. 
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Semaphore Definition 


The simplest semaphore is a variable that can take only the values 0 and 1, a binary semaphore. This is the 
most common form. Semaphores that can take many positive values are called general semaphores. For the 
remainder of this chapter, we concentrate on binary semaphores. 


The definitions of P and Vv are surprisingly simple. Suppose you have a semaphore variable sv. The two 
operations are then defined as follows: 


P(sv) If sv is greater than zero, decrement sv. If sv is zero, suspend execution 
of this process. 


V(sv) If some other process has been suspended waiting for sv, make it resume 
execution. If no process is suspended waiting for sv, increment sv. 


Another way of thinking about semaphores is that the semaphore variable, sv, is true when the critical 
section is available, is decremented by P (sv) so it’s false when the critical section is busy, and is incre- 
mented by v (sv) when the critical section is again available. Be aware that simply having a normal vari- 
able that you decrement and increment is not good enough, because you can’t express in C, C++, C#, or 
almost any conventional programming language the need to make a single, atomic operation of the test 
to see whether the variable is true, and if so change the variable to make it false. This is what makes 
the semaphore operations special. 


A Theoretical Example 


You can see how this works with a simple theoretical example. Suppose you have two processes proc1 
and proc2, both of which need exclusive access to a database at some point in their execution. You define 
a single binary semaphore, sv, which starts with the value 1 and can be accessed by both processes. Both 
processes then need to perform the same processing to access the critical section of code; indeed, the 

two processes could simply be different invocations of the same program. 


The two processes share the sv semaphore variable. Once one process has executed P (sv), it has 
obtained the semaphore and can enter the critical section. The second process is prevented from enter- 
ing the critical section because when it attempts to execute P (sv), it’s made to wait until the first 
process has left the critical section and executed V(sv) to release the semaphore. 


The required pseudocode is identical for both processes: 
semaphore sv = 1; 
loop forever { 
P(sv); 
critical code section; 


V(sv) ; 
noncritical code section; 


The code is surprisingly simple because the definition of the P and v operations is very powerful. 
Figure 14-1 shows a diagram showing how the P and v operations act as a gate into critical sections of code. 


579 


Chapter 14: Semaphores, Shared Memory, and Message Queues 


Process A thread Process B thread 
of execution of execution 








P semaphore operation 


Non-critical section Critical Non-critical section 
of process A section of process B 


-- Only a single 
thread of execution 
can enter the critical 
section at any 
one time 


V semaphore operation 


Figure 14-1 


Linux Semaphore Facilities 


Now that you’ve seen what semaphores are and how they work in theory, you can look at how the fea- 
tures are implemented in Linux. The interface is rather elaborate and offers far more facilities than are 
generally required. All the Linux semaphore functions operate on arrays of general semaphores rather 
than a single binary semaphore. At first sight, this just seems to make things more complicated, but in 
complex cases where a process needs to lock multiple resources, the ability to operate on an array of 
semaphores is a big advantage. In this chapter, we concentrate on using single semaphores, because in 
most cases that’s all you will need to use. 


The semaphore function definitions are 
#include <sys/sem.h> 


int semctl(int sem_id, int sem_num, int command, ...); 
int semget (key_t key, int num sems, int sem flags); 
int semop(int sem_id, struct sembuf *sem_ops, size_t num sem_ ops); 


The header file sys/sem.h usually relies on two other header files, sys/types.hand sys/ipc.h. 
Normally they are automatically included by sys/sem.h and you do not need to explicitly add a 
#include for them. 


As you work through each function in turn, remember that these functions were designed to work for 
arrays of semaphore values, which makes their operation significantly more complex than would have 
been required for a single semaphore. 


Notice that key acts very much like a filename in that it represents a resource that programs may use 
and cooperate in using if they agree on a common name. Similarly, the identifier returned by semget 
and used by the other shared memory functions is very much like the FILE * file stream returned 

by fopen in that it’s a value used by the process to access the shared file. Just as with files different 
processes will have different semaphore identifiers, though they refer to the same semaphore. This use 
of a key and identifiers is common to all of the IPC facilities discussed here, although each facility uses 
independent keys and identifiers. 
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semget 


The semget function creates a new semaphore or obtains the semaphore key of an existing semaphore: 
int semget(key_t key, int num_sems, int sem flags); 


The first parameter, key, is an integral value used to allow unrelated processes to access the same sema- 
phore. All semaphores are accessed indirectly by the program supplying a key, for which the system then 
generates a semaphore identifier. The semaphore key is used only with semget. All other semaphore 
functions use the semaphore identifier returned from semget. 


There is a special semaphore key value, IPC_PRIVATE, that is intended to create a semaphore that only 
the creating process could access, but this rarely has any useful purpose. You should provide a unique, 
non-zero integer value for key when you want to create a new semaphore. 


The num_sems parameter is the number of semaphores required. This is almost always 1. 


The sem_flags parameter is a set of flags, very much like the flags to the open function. The lower nine 
bits are the permissions for the semaphore, which behave like file permissions. In addition, these can be bit- 
wise ORed with the value IPC_CREAT to create a new semaphore. It’s not an error to have the IPC_CREAT 
flag set and give the key of an existing semaphore. The IPC_CREAT flag is silently ignored if it is not 
required. You can use IPC_CREAT and IPC_EXCL together to ensure that you obtain a new, unique sema- 
phore. It will return an error if the semaphore already exists. 











The semget function returns a positive (nonzero) value on success; this is the semaphore identifier used 
in the other semaphore functions. On error, it returns —1. 


semop 


The function semop is used for changing the value of the semaphore: 
int semop(int sem_id, struct sembuf *sem_ops, size_t num_sem_ops); 


The first parameter, sem_id, is the semaphore identifier, as returned from semget. The second parameter, 
sem_ops, is a pointer to an array of structures, each of which will have at least the following members: 


struct sembuf { 
short sem_num; 
short sem_op; 
short sem_flg; 


The first member, sem_num, is the semaphore number, usually 0 unless you’re working with an array 

of semaphores. The sem_op member is the value by which the semaphore should be changed. (You can 
change a semaphore by amounts other than 1.) In general, only two values are used, —1, which is your P 
operation to wait for a semaphore to become available, and +1, which is your v operation to signal that a 
semaphore is now available. 


The final member, sem_f1g, is usually set to SEM_UNDO. This causes the operating system to track the 


changes made to the semaphore by the current process and, if the process terminates without releasing 
the semaphore, allows the operating system to automatically release the semaphore if it was held by this 
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process. It’s good practice to set sem_flg to SEM_UNDO, unless you specifically require different behavior. 
If you do decide you need a value other than SEM_UNDO, it’s important to be consistent, or you can get very 
confused as to whether the kernel is attempting to “tidy up” your semaphores when your process exits. 


All actions called for by semop are taken together to avoid a race condition implied by the use of multiple 
semaphores. You can find full details of the processing of semop in the manual pages. 


semctl 


The semct1 function allows direct control of semaphore information: 
int semctl(int sem_id, int sem_num, int command, ...); 


The first parameter, sem_id, is a semaphore identifier, obtained from semget. The sem_num parameter 
is the semaphore number. You use this when you’re working with arrays of semaphores. Usually, this is 
0, the first and only semaphore. The command parameter is the action to take, and a fourth parameter, if 
present, is a union semun, which according to the X/OPEN specification must have at least the follow- 
ing members: 


union semun { 
int val; 
struct semid_ds *buf; 
unsigned short *array; 


Most versions of Linux have a definition of the semun union in a header file (usually sem.h), though 
X/Open does say that you have to declare your own. If you do find that you need to declare your own, 
check the manual pages for semct1 to see if there is a definition given. If there is, we suggest you use 
exactly the definition given in your manual, even if it differs from that given here. 


There are many different possible values of command allowed for semct1. Only the two that we describe 
here are commonly used. For full details of the semct1 function, you should consult the manual page. 


The two common values of command are: 





Q SETVAL: Used for initializing a semaphore to a known value. The value required is passed as the 
val member of the union semun. This is required to set the semaphore up before it’s used for 
the first time. 





Q IPC_RMID: Used for deleting a semaphore identifier when it’s no longer required. 





The semct1 function returns different values depending on the command parameter. For SETVAL and 
IPC_RMID it returns 0 for success and —1 on error. 


Using Semaphores 


As you can see from the previous section’s descriptions, semaphore operations can be rather complex. 
This is most unfortunate, because programming multiple processes or threads with critical sections is 

quite a difficult problem on its own and having a complex programming interface simply adds to the 

intellectual burden. 
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Fortunately you can solve most problems that require semaphores using only a single binary semaphore, 
the simplest type. In the following example, you use the full programming interface to create a much 
simpler P and v type interface for a binary semaphore. You then use this much simpler interface to 
demonstrate how semaphores function. 


To experiment with semaphores, you use a single program, sem1 .c, that you can invoke several times. 
You use an optional parameter to specify whether the program is responsible for creating and destroying 
the semaphore. 


You use the output of two different characters to indicate entering and leaving the critical section. The 
program invoked with a parameter prints an X on entering and exiting its critical section. Other invoca- 
tions of the program print an O on entering and exiting their critical sections. Because only one process 
should be able to enter its critical section at any given time, all x and 0 characters should appear in pairs. 


Try It Out Semaphores 


1. After the system #includes, you include a file semun .h. This defines the union semun, as 
required by X/OPEN, if the system include sys/sem.h doesn’t already define it. Then come the 
function prototypes, and the global variable, before you come to the main function. There the sem- 
aphore is created with a call to semget, which returns the semaphore ID. If the program is the first 
to be called (that is, it’s called with a parameter and argc > 1),a call is made to set_semvalue to 
initialize the semaphore and op_char is set to x: 


#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <sys/sem.h> 
#include "semun.h" 
static int set_semvalue(void) ; 
static void del_semvalue (void) ; 
static int semaphore_p(void); 
static int semaphore_v(void) ; 
static int sem_id; 
int main(int argc, char *argv[]) 
{ 
Tiss 
int pause_time; 
ghar op ehar =. 44> 
srand((unsigned int) getpid()); 


sem_id = semget((key_t)1234, 1, 0666 | IPC_CREAT); 


menange a 


583 


Chapter 14: Semaphores, Shared Memory, and Message Queues 


584 


if (!set_semvalue()) { 
fprintf(stderr, 
exit (EXIT_FAILURE) ; 
} 

op_char 


sleep (2); 


= 'X'; 


2. 


call to semaphore_p, which sets the semaphore 
critical section: 


for(i ore E 
if (!semaphore_p()) 
printf ("%c", op_char) ;fflush (stdout) 
pause_time rand() % 3; 

sleep (pause_time) ; 


printf ("%c", op_char) ;fflush (stdout) 


"Failed to initialize semaphore\n"); 


Then you have a loop that enters and leaves the critical section 10 times. There you first make a 


to wait as this program is about to enter the 





exit (EXIT_FAILURE) ; 


1 


1 


After the critical section, you call semaphore_v, setting the semaphore as available, before 


going through the for loop again after a random wait. After the loop, the call to del_semvalue 


is made to clean up the code: 


if (!semaphore_v() ) 


De 


pause_time = rand() % 
sleep (pause_time) ; 
} 


printf ("\n%d - finished\n", getpid()); 


1£ (arge > 1) { 
sleep (10); 
del_semvalue() ; 
} 


exit (EXIT_SUCCESS) ; 





exit (EXIT_FAILURE) ; 


The function set_semvalue initializes the semaphore using the SETVAL command in a semct1 


call. You need to do this before you can use the semaphore: 


static int set_semvalue (void) 
{ 


union semun sem_union; 
een union, val. = 16 

if (semctl(sem_id, 0, 
return(1); 





SETVAL, sem_union) 
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5. The del_semvalue function has almost the same form, except that the call to semct1 uses the 
command IPC_RMID to remove the semaphore’s ID: 


static void del_semvalue (void) 
{ 


union semun sem_union; 


if (semctl(sem_id, 0, IPC_RMID, sem_union) == -1) 
fprintf(stderr, "Failed to delete semaphore\n") ; 
6. semaphore_p changes the semaphore by —1. This is the “wait” operation: 
static int semaphore_p(void) 
{ 


struct sembuf sem_b; 


sem_b.sem_num = 0; 





sem_b.sem_op = -1; /* P() */ 

sem_b.sem_flg = SEM_UNDO; 

if (semop(sem_id, &sem_b, 1) == -1) { 
fprintf(stderr, "semaphore_p failed\n"); 
return (0); 

} 

return (1); 


7. semaphore_v is similar except for setting the sem_op part of the sembuf structure to 1. This is 
the “release” operation, so that the semaphore becomes available: 


static int semaphore_v (void) 


{ 
struct sembuf sem_b; 


sem_b.sem_num = 0; 
Semis Seis S ihe fe Ww) o/ 
sem_b.sem_flg = SEM_UNDO; 





if (semop(sem_id, &sem_b, 1) == -1) { 
fprintf(stderr, "semaphore_v failed\n"); 
return (0); 

} 

return (1); 


Notice that this simple program allows only a single binary semaphore per program, although you 
could extend it to pass the semaphore variable if you need more semaphores. Normally, a single binary 
semaphore is sufficient. 


You can test your program by invoking it several times. The first time, you pass a parameter to tell 


the program that it’s responsible for creating and deleting the semaphore. The other invocations have 
no parameter. 
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Here’s some sample output, with two invocations of the program. 


$ cc seml.c -o seml 

$ ./seml 1 & 

[1] 1082 

$ ./sem1 
OOXXOOXXOOXXOOXXOOXXOOOOXXOOXXOOXXOOXXXK 
1083 - finished 

1082 - finished 

$ 


Remember that “O” represents the first invocation of the program, and “X” the second invocation of the 
program. Because each program prints a character as it enters and again as it leaves the critical section, 
each character should only appear as part of a pair. As you can see, the Os and xs are indeed properly 
paired, indicating that the critical section is being correctly processed. If this doesn’t work on your par- 
ticular system, you may have to use the command stty -tostop before invoking the program to 
ensure that the background program generating tty output does not cause a signal to be generated. 


How It Works 


The program starts by obtaining a semaphore identity from the (arbitrary) key that you’ve chosen using 
the semget function. The IPC_CREAT flag causes the semaphore to be created if one is required. 


If the program has a parameter, it’s responsible for initializing the semaphore, which it does with the func- 
tion set_semvalue, a simplified interface to the more general semct1 function. It also uses the presence of 
the parameter to determine which character it should print out. The sleep simply allows you some time to 
invoke other copies of the program before this copy gets to execute too many times around its loop. You 
use srand and rand to introduce some pseudo-random timing into the program. 


The program then loops 10 times, with pseudo-random waits in its critical and noncritical sections. The 
critical section is guarded by calls to your semaphore_p and semaphore_v functions, which are simpli- 
fied interfaces to the more general semop function. 


Before it deletes the semaphore, the program that was invoked with a parameter then waits to allow 
other invocations to complete. If the semaphore isn’t deleted, it will continue to exist in the system even 
though no programs are using it. In real programs, it’s very important to ensure you don’t unintention- 
ally leave semaphores around after execution. It may cause problems next time you run the program, 
and semaphores are a limited resource that you must conserve. 


Shared Memory 


Shared memory is the second of the three IPC facilities. It allows two unrelated processes to access the 
same logical memory. Shared memory is a very efficient way of transferring data between two running 
processes. Although the X/Open standard doesn’t require it, it’s probable that most implementations 
of shared memory arrange for the memory being shared between different processes to be the same 
physical memory. 
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Shared memory is a special range of addresses that is created by IPC for one process and appears in the 
address space of that process. Other processes can then “attach” the same shared memory segment into 
their own address space. All processes can access the memory locations just as if the memory had been 
allocated by malloc. If one process writes to the shared memory, the changes immediately become visible 
to any other process that has access to the same shared memory. 


Shared memory provides an efficient way of sharing and passing data between multiple processes. By 
itself, shared memory doesn’t provide any synchronization facilities. Because it provides no synchro- 
nization facilities, you usually need to use some other mechanism to synchronize access to the shared 
memory. Typically, you might use shared memory to provide efficient access to large areas of memory 
and pass small messages to synchronize access to that memory. 


There are no automatic facilities to prevent a second process from starting to read the shared memory 


before the first process has finished writing to it. It’s the responsibility of the programmer to synchronize 
access. Figure 14-2 shows an illustration of how shared memory works. 


Physical memory 





Logical address space Logical address space 
for process A for process B 








Shared 
Memory, 
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Figure 14-2 
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The arrows show the mapping of the logical address space of each process to the physical memory 
available. In practice, the situation is more complex because the available memory actually consists of 
a mix of physical memory and memory pages that have been swapped out to disk. 


The functions for shared memory resemble those for semaphores: 
#include <sys/shm.h> 


void *shmat(int shm_id, const void *shm_addr, int shmflg); 
int shmctl(int shm_id, int cmd, struct shmid_ds *buf); 
int shmdt(const void *shm addr); 

int shmget(key_t key, size_t size, int shmflg); 


As with semaphores, the include files sys/types.h and sys/ipc .h are normally automatically 
included by shm.h. 


shmget 


You create shared memory using the shmget function: 
int shmget(key_t key, size_t size, int shmflg); 


As with semaphores, the program provides key, which effectively names the shared memory segment, 
and the shmget function returns a shared memory identifier that is used in subsequent shared memory 
functions. There’s a special key value, IPC_PRIVATE, that creates shared memory private to the process. 
You wouldn’t normally use this value, and you may find the private shared memory is not actually pri- 
vate on some Linux systems. 


The second parameter, size, specifies the amount of memory required in bytes. 


The third parameter, shmf£1g, consists of nine permission flags that are used in the same way as the mode 
flags for creating files. A special bit defined by IPC_CREAT must be bitwise ORed with the permissions to 

create a new shared memory segment. It’s not an error to have the IPC_CREAT flag set and pass the key of 
an existing shared memory segment. The IPC_CREAT flag is silently ignored if it is not required. 





The permission flags are very useful with shared memory because they allow a process to create shared 
memory that can be written by processes owned by the creator of the shared memory, but only read by 
processes that other users have created. You can use this to provide efficient read-only access to data 
by placing it in shared memory without the risk of its being changed by other users. 


If the shared memory is successfully created, shmget returns a nonnegative integer, the shared memory 
identifier. On failure, it returns —1. 


shmat 


When you first create a shared memory segment, it’s not accessible by any process. To enable access to the 
shared memory, you must attach it to the address space of a process. You do this with the shmat function: 


void *shmat (int shm_id, const void *shm_addr, int shmflg); 
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The first parameter, shm_id, is the shared memory identifier returned from shmget. 


The second parameter, shm_addr, is the address at which the shared memory is to be attached to the 
current process. This should almost always be a null pointer, which allows the system to choose the 
address at which the memory appears. 


The third parameter, shmf1g, is a set of bitwise flags. The two possible values are SHM_RND, which, in con- 
junction with shm_addr, controls the address at which the shared memory is attached, and SHM_RDONLY, 
which makes the attached memory read-only. It’s very rare to need to control the address at which shared 
memory is attached; you should normally allow the system to choose an address for you, because doing 
otherwise will make the application highly hardware-dependent. 


If the shmat call is successful, it returns a pointer to the first byte of shared memory. On failure -1 
is returned. 


The shared memory will have read or write access depending on the owner (the creator of the shared 
memory), the permissions, and the owner of the current process. Permissions on shared memory are 


similar to the permissions on files. 


An exception to this rule arises if shmf1lg & SHM_RDONLY is true. Then the shared memory won’t be 
writable, even if permissions would have allowed write access. 


shmdt 


The shmdt function detaches the shared memory from the current process. It takes a pointer to the address 
returned by shmat. On success, it returns 0, on error —1. Note that detaching the shared memory doesn’t 
delete it; it just makes that memory unavailable to the current process. 


shmcetl 


The control functions for shared memory are (thankfully) somewhat simpler than the more complex 
ones for semaphores: 


int shmctl(int shm_id, int command, struct shmid_ds *buf); 
The shmid_ds structure has at least the following members: 
struct shmid_ds { 
uid_t shm_perm.uid; 
uid_t shm_perm.gid; 
mode_t shm_perm.mode; 


The first parameter, shm_id, is the identifier returned from shmget. 


The second parameter, command, is the action to take. It can take three values, shown in the following table. 
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Command 


IPC_STAT 


IPC_SET 


IPC_RMID 


Description 


Sets the data in the shmid_ds structure to reflect the values associated 
with the shared memory. 


Sets the values associated with the shared memory to those provided in 
the shmid_ds data structure, if the process has permission to do so. 


Deletes the shared memory segment. 


The third parameter, buf, is a pointer to the structure containing the modes and permissions for the 
shared memory. 


On success, it returns 0, on failure, -1. X/Open doesn’t specify what happens if you attempt to delete a 
shared memory segment while it’s attached. Generally, a shared memory segment that is attached but 
deleted continues to function until it has been detached from the last process. However, because this 
behavior isn’t specified, it’s best not to rely on it. 


Try It Out 


Shared Memory 


Now that you’ve seen the shared memory functions, you can write some code to use them. In this Try 

It Out, you write a pair of programs, shm1 .c and shm2 .c. The first (the consumer) will create a shared 
memory segment and then display any data that is written into it. The second (the producer) will attach 
to an existing shared memory segment and allow you to enter data into that segment. 


1. First create a common header file to describe the shared memory you want to pass around. Call 
this shm_com.h: 


#define TEXT_SZ 2048 


struct shared_use_st { 
int written_by_you; 
char some_text [TEXT_SZ]; 


be 


This defines a structure to use in both the consumer and producer programs. You use an int 
flag written_by_you to tell the consumer when data has been written to the rest of the struc- 
ture and arbitrarily decide that you need to transfer up to 2k of text. 


2. Thefirst program, shm1 .c, is the consumer. After the headers, the shared memory segment 
(the size of your shared memory structure) is created with a call to shmget, with the LPC_CREAT 
bit specified: 


#include 
#include 
#include 
#include 


#include 
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#include "shm_com.h" 


int main() 


{ 


5. 


EEA a 


void *shared_memory = (void *)0; 
struct shared_use_st *shared_stuff; 
int shmid; 


srand((unsigned int) getpid()); 





shmid = shmget((key_t)1234, sizeof(struct shared_use_st), 0666 | IPC_CREAT) ; 


at. (shitid =S1)) 4 
fprintf(stderr, "shmget failed\n"); 
exit (EXIT_FAILURE) ; 





You now make the shared memory accessible to the program: 


shared_memory = shmat(shmid, (void *)0, 0); 

if (shared_memory == (void *)-1) { 
fprintf(stderr, "shmat failed\n") ; 
exit (EXIT_FAILURE) ; 





printf ("Memory attached at %X\n", (int)shared_memory) ; 


The next portion of the program assigns the shared_memory segment to shared_stuff, 
which then prints out any text in written_by_you. The loop continues until end is found in 
written_by_you. The call to sleep forces the consumer to sit in its critical section, which 
makes the producer wait: 


shared_stuff = (struct shared_use_st *)shared_memory; 
shared_stuff->written_by_you = 0; 
while(running) { 
if (shared_stuff->written_by_you) { 
printf("You wrote: %s", shared_stuff->some_text) ; 


sleep( rand() % 4 ); /* make the other process wait for us ! */ 
shared_stuff->written_by_you = 0; 
if (strncemp(shared_stuff->some_text, "end", 3) == 0) { 


icivugialsliaye; = (Op 


Finally, the shared memory is detached and then deleted: 


if (shmdt(shared_memory) == -1) { 
fprintf(stderr, "shmdt failed\n") ; 
exit (EXIT_FAILURE) ; 





if (shmctl(shmid, IPC_RMID, 0) == -1) { 
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fprintf(stderr, "shmctl(IPC_RMID) failed\n"); 
exit (EXIT_FAILURE) ; 


exit (EXIT_SUCCESS) ; 


6. The second program, shm2 .c, is the producer; it allows you to enter data for consumers. It’s 
very similar to shm1.c and looks like this: 


#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 


#include <sys/shm.h> 
#include "shm_com.h" 


int main() 

{ 
iin reWhaualstiays; = JL p 
void *shared_memory = (void *)0; 
struct shared_use_st *shared_stuff; 
char buffer[BUFSIZ]; 
int shmid; 


shmid = shmget((key_t)1234, sizeof(struct shared_use_st), 0666 | IPC_CREAT) ; 


if (shmid == -1) { 
fprintf(stderr, "shmget failed\n"); 
exit (EXIT_FAILURE) ; 
} 
shared_memory = shmat(shmid, (void *)0, 0); 
if (shared_memory == (void *)-1) { 
fprintf(stderr, "shmat failed\n") ; 
exit (EXIT_FAILURE) ; 
} 


printf("Memory attached at %X\n", (int)shared_memory) ; 


shared_stuff = (struct shared_use_st *)shared_memory; 
while(running) { 
while (shared_stuff->written_by_you == 1) { 
sleep(1); 
printf ("waiting for client...\n"); 
} 
printf("Enter some text: "); 
fgets(buffer, BUFSIZ, stdin); 


strncpy (shared_stuff->some_text, buffer, TEXT_SZ); 
shared_stuff->written_by_you = 1; 
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it (Seienemo(lowtiee, Neal”, 3) == 0) *€ 
running = 0; 


} 
if (shmdt(shared_memory) == -1) { 


fprintf(stderr, "shmdt failed\n") ; 
exit (EXIT_FAILURE) ; 





} 
exit (EXIT_SUCCESS) ; 





When you run these programs, you get sample output such as this: 


$ ./shm1 & 

[1] 294 

Memory attached at 40017000 
$ ./shm2 

Memory attached at 40017000 
Enter some text: hello 

You wrote: hello 

waiting for client... 
waiting for client... 

Enter some text: Linux! 

You wrote: Linux! 

waiting for client... 
waiting for client... 
waiting for client... 

Enter some text: end 

You wrote: end 


$ 


How It Works 


The first program, shm1, creates the shared memory segment and then attaches it to its address 

space. You impose a structure, shared_use_st on the first part of the shared memory. This has a flag, 
written_by_you, which is set when data is available. When this flag is set, the program reads the 
text, prints it out, and clears the flag to show it has read the data. Use the special string, end, to allow 
a clean exit from the loop. The program then detaches the shared memory segment and deletes it. 


The second program, shm2, gets and attaches the same shared memory segment, because it uses the 
same key, 1234. It then prompts the user to enter some text. If the flag written_by_you is set, shm2 
knows that the client process hasn’t yet read the previous data and waits for it. When the other process 
clears this flag, shm2 writes the new data and sets the flag. It also uses the magic string end to terminate 
and detach the shared memory segment. 


Notice that you had to provide your own, rather crude synchronization flag, writ ten_by_you, which 
involves a very inefficient busy wait (by continuously looping). This keeps the example simple, however in 
real programs you would have used a semaphore, or perhaps passed a message, either using a pipe or IPC 
messages (which we discuss in the next section), or generated a signal (as shown in Chapter 11) to provide 
a more efficient synchronization mechanism between the reading and writing parts of the application. 
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Message Queues 


We'll now take a look at the third and final System V IPC facility: message queues. In many ways, message 
queues are like named pipes, but without the complexity associated with opening and closing the pipe. 
However, using messages doesn’t get you away from the problems that you have with named pipes, 
such as blocking on full pipes. 


Message queues provide a reasonably easy and efficient way of passing data between two unrelated 
processes. They have the advantage over named pipes that the message queue exists independently of 
both the sending and receiving processes, which removes some of the difficulties that occur in synchro- 
nizing the opening and closing of named pipes. 


Message queues provide a way of sending a block of data from one process to another. Additionally, 
each block of data is considered to have a type, and a receiving process may receive blocks of data 
having different type values independently. The good news is that you can almost totally avoid the 
synchronization and blocking problems of named pipes by sending messages. Even better, you can 
“look ahead” for messages that are urgent in some way. The bad news is that, just like pipes, there’s a 
maximum size limit imposed on each block of data and also a limit on the maximum total size of all 
blocks on all queues throughout the system. 


While stating that these limits are imposed, the X/Open specification offers no way of discovering what 
the limits are, except that exceeding them is a valid reason for some message queue functions to fail. 
Linux does have two defines, MSGMAX and MSGMNB, which define the maximum size in bytes of an indi- 
vidual message and the maximum size of a queue, respectively. These macros may be different or, for 
that matter, not even present on other systems. 


The message queue function definitions are: 
#include <sys/msg.h> 


int msgctl(int msqid, int cmd, struct msqid_ds *buf); 

int msgget(key_t key, int msgflg); 

int msgrcv(int msqid, void *msg_ ptr, size_t msg_sz, long int msgtype, int msgflg); 
int msgsnd(int msqid, const void *msg_ ptr, size_t msg_sz, int msgflg); 


As with semaphores and shared memory, the include files sys/types.h and sys/ipc.h are normally 
automatically included by msg .h. 


msgget 


You create and access a message queue using the msgget function: 
int msgget(key_t key, int msgflg); 


The program must provide a key value that, as with other IPC facilities, names a particular message queue. 
The special value IPC_PRIVATE creates a private queue, which in theory is accessible only by the current 
process. As with semaphores and messages, on some Linux systems the message queue may not actually 
be private. Because a private queue has very little purpose, that’s not a significant problem. As before, the 
second parameter, msgf1g, consists of nine permission flags. A special bit defined by IPC_CREAT must be 
bitwise ORed with the permissions to create a new message queue. It’s not an error to set the IPC_CREAT 








594 


Chapter 14: Semaphores, Shared Memory, and Message Queues 


flag and give the key of an existing message queue. The IPC_CREAT flag is silently ignored if the message 
queue already exists. 


The msgget function returns a positive number, the queue identifier, on success or —1 on failure. 


msgsnd 


The msgsnd function allows you to add a message to a message queue: 

int msgsnd(int msqid, const void *msg_ ptr, size_t msg_sz, int msgflg); 
The structure of the message is constrained in two ways. First, it must be smaller than the system limit, 
and second, it must start with a long int, which will be used as a message type in the receive function. 
When you're using messages, it’s best to define your message structure something like this: 

struct my_message { 


long int message_type; 
/* The data you wish to transfer */ 


Because the message_type is used in message reception, you can’t simply ignore it. You must declare 
your data structure to include it, and it’s also wise to initialize it so that it contains a known value. 
The first parameter, msqid, is the message queue identifier returned from a msgget function. 


The second parameter, msg_ptr, is a pointer to the message to be sent, which must start with a long 
int type as described previously. 


The third parameter, msg_sz, is the size of the message pointed to by msg_ptr. This size must not 
include the long int message type. 


The fourth parameter, msgf1g, controls what happens if either the current message queue is full or 
the systemwide limit on queued messages has been reached. If msgf£1g has the IPC_NOWAIT flag 

set, the function will return immediately without sending the message and the return value will be —-1. 
If the msg£1g has the IPC_NOWAIT flag clear, the sending process will be suspended, waiting for space 
to become available in the queue. 


On success, the function returns 0, on failure —1. If the call is successful, a copy of the message data has 
been taken and placed on the message queue. 


msgrcev 


The msgrcv function retrieves messages from a message queue: 
int msgrcv(int msqid, void *msg_ptr, size_t msg_sz, long int msgtype, int msgflg); 
The first parameter, msqid, is the message queue identifier returned from a msgget function. 


The second parameter, msg_ptr, is a pointer to the message to be received, which must start with a long 
int type as described previously in the msgsnd function. 
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The third parameter, msg_sz, is the size of the message pointed to by msg_ptr, not including the long 
int message type. 


The fourth parameter, msgtype, isa long int, which allows a simple form of reception priority to be 
implemented. If msgtype has the value 0, the first available message in the queue is retrieved. If it’s 
greater than zero, the first message with the same message type is retrieved. If it’s less than zero, the first 
message that has a type the same as or less than the absolute value of msgtype is retrieved. 


This sounds more complicated than it actually is in practice. If you simply want to retrieve messages in 
the order in which they were sent, set msgtype to 0. If you want to retrieve only messages with a specific 
message type, set msgtype equal to that value. If you want to receive messages with a type of n or 
smaller, set msgtype to -n. 


The fifth parameter, msg£1g, controls what happens when no message of the appropriate type is waiting 
to be received. If the IPc_NOwAIT flag in msgf1g is set, the call will return immediately with a return 
value of —1. If the IPc_NowarT flag of msgf1g is clear, the process will be suspended, waiting for an 
appropriate type of message to arrive. 


On success, msgrcv returns the number of bytes placed in the receive buffer, the message is copied into 
the user-allocated buffer pointed to by msg_ptr, and the data is deleted from the message queue. It 
returns —1 on error. 


msgctl 


The final message queue function is msgct1, which is very similar to that of the control function for 
shared memory: 


int msgctl(int msqid, int command, struct msqid_ds *buf); 
The msqid_ds structure has at least the following members: 
struct msqid_ds { 
uid_t msg _perm.uid; 


uid_t msg_perm.gid 
mode_t msg_perm.mode; 


The first parameter, msqid, is the identifier returned from msgget. 


The second parameter, command, is the action to take. It can take three values, described in the follow- 
ing table: 


Command Description 


IPC_STAT Sets the data in the msqid_ds structure to reflect the values associated with 
the message queue. 


IPC_SET If the process has permission to do so, this sets the values associated with 
the message queue to those provided in the msqid_ds data structure. 


IPC_RMID Deletes the message queue. 
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0 is returned on success, —1 on failure. If a message queue is deleted while a process is waiting ina 
msgsnd or msgrcv function, the send or receive function will fail. 


Try It Out Message Queues 


Now that you’ve seen the definitions for message queues, you can see how they work in practice. As 
before, you'll write two programs: msg1 .c to receive and msg2 .c to send. You'll allow either program 
to create the message queue, but use the receiver to delete it after it receives the last message. 


1. Here’s the receiver program, msg1 .c: 


#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 
#include <errno.h> 
#include <unistd.h> 


#include <sys/msg.h> 


struct my_msg_st { 
long int my_msg_type; 
char some_text [BUFSIZ]; 
TE 


int main() 
{ 
Lae icWhalasliaye; = ike 
int msgid; 
struct my_msg_st some_data; 
long int msg_to_receive = 0; 


2. First, set up the message queue: 
msgid = msgget((key_t)1234, 0666 | IPC_CREAT); 
IMSG == iL) 


fprintf(stderr, "msgget failed with error: %d\n", errno); 
exit (EXIT_FAILURE) ; 





3. Then the messages are retrieved from the queue until an end message is encountered. Finally, 
the message queue is deleted: 


while(running) { 
if (msgrcv(msgid, (void *)&some_data, BUFSIZ, 
msg_to_receive, 0) == -1) { 
fprintf(stderr, "msgrcv failed with error: %d\n", errno); 
exit (EXIT_FAILURE) ; 





} 

printf ("You wrote: %s", some_data.some_text); 

if (strncmp(some_data.some_text, "end", 3) == 0) { 
running = 0; 
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if (msgctl (msgid, IPC_RMID, 0) == -1) { 
fprintf(stderr, "msgctl(IPC_RMID) failed\n"); 
exit (EXIT_FAILURE) ; 

} 


exit (EXIT_SUCCESS) ; 


The sender program, msg2 .c, is very similar to msg1 .c. In the main setup, delete the 
msg_to_receive declaration, and replace it with buffer [BUFSIZ]. Remove the message 
queue delete, and make the following changes to the running loop. You now have a call to 
msgsnd to send the entered text to the queue. The program msg2 .c is shown here with the 
differences from msg1 .c highlighted: 


#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 
#include <errno.h> 
#include <unistd.h> 


#include <sys/msg.h> 


#define MAX TEXT 512 


struct my_msg_st { 


hi 


long int my_msg_type; 
char some_text [MAX_TEXT]; 


int main() 


{ 


int running = 1; 

struct my_msg_st some_data; 
int msgid; 

char buffer [BUFSIZ]; 


msgid = msgget ( (key_t)1234, 0666 | IPC_CREAT); 


if (msgid == -1) { 
fprintf(stderr, "msgget failed with error: %d\n", errno) ; 
exit (EXIT_FAILURE) ; 

} 


while(running) { 
printf("Enter some text: "); 
fgets(buffer, BUFSIZ, stdin); 
some_data.my_msg_type = 1; 
strcpy (some_data.some_text, buffer); 
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if (msgsnd(msgid, (void *)&some_data, MAX_TEXT, 0) == -1) { 
fprintf(stderr, "msgsnd failed\n"); 
exit (EXIT_FAILURE) ; 





} 
PERS CEN CMPL DUR Er A enS EEO 
running = 0; 


} 





exit (EXIT_SUCCESS) ; 


Unlike in the pipes example, there’s no need for the processes to provide their own synchronization 
method. This is a significant advantage of messages over pipes. 


Providing there’s room in the message queue, the sender can create the queue, put some data into 
the queue, and then exit before the receiver even starts. You'll run the sender, msg2, first. Here’s some 
sample output: 


S ./msg2 

Enter some text: hello 

Enter some text: How are you today? 
Enter some text: end 

$ ./msg1 

You wrote: hello 

You wrote: How are you today? 

You wrote: end 


$ 


How It Works 


The sender program creates a message queue with msgget; then it adds messages to the queue with 
msgsnd. The receiver obtains the message queue identifier with msgget and then receives messages 
until the special text end is received. It then tidies up by deleting the message queue with msgct1. 


The CD Database Application 


You're now in a position to modify your CD database application to use the IPC facilities that you’ve 
seen in this chapter. 


You could use many different combinations of the three IPC facilities, but because the information you 
need to pass is quite small, it’s sensible to implement the passing of requests and responses directly 
using message queues. 


If the amounts of data that you needed to pass were large, you could have considered passing the actual 


data in shared memory and using either semaphores or messages to pass a “token” to inform the other 
process that data was available in shared memory. 
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The message queue interface removes the problem that you had in Chapter 11, where you needed both 
processes to have the pipe open while data was passed. Using message queues allows one process to put 
messages in the queue, even if that process is currently the only user of the queue. 


The only significant decision you need to make is how to return answers to clients. A simple choice would 
be to have one queue for the server and one queue for each client. If there were a large number of simulta- 
neous clients, this could cause problems by requiring a large number of message queues. By using the mes- 
sage ID field in the message, you can allow all the clients to use a single queue and “address” response 
messages to particular client processes by using the client process ID in the message. Each client can then 
retrieve messages addressed only to itself, leaving messages for other clients in the queue. 


To convert your CD application to use IPC facilities, you need to replace only the file pipe_imp.c from 
the code accompanying Chapter 13. In the following pages, we describe the principal sections of the 
replacement file, ipc_imp.c. 


Revising the Server Functions 


First you need to update the server functions. 


1. First, include the appropriate headers, declare some message queue keys, and define a structure 
to hold your message data: 


#include "cd_data.h" 
#include "cliserv.h" 


#include <sys/msg.h> 


#define SERVER_MQUEUE 1234 
#define CLIENT_MQUEUE 4321 


struct msg_passed { 
long int msg_key; /* used for client pid */ 
message_db_t real_message; 





i 
2. Two variables with file scope hold the two queue identifiers returned from the msgget function: 


Sea ETORREN CEVEA eal 
SENEO EEC E 


3: Make the server responsible for creating both message queues: 


int server_starting() 
{ 
#if£ DEBUG_TRACE 
printf("sd :- server_starting()\n", getpid()); 
#endif 





serv_qid = msgget((key_t) SERVER_MQUEUE, 0666 | IPC_CREAT) ; 
if (serv_qid == -1) return(0); 
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cli_qid = msgget((key_t) CLIENT_MQUEUE, 0666 | IPC_CREAT) ; 
aie (eilat_ nie) = il) seeieuiein (0) 5 


return(1); 
The server is also responsible for tidying up if it ever exits. When the server ends, you set your 


file-scope variables to illegal values. This will catch any bugs if the server attempts to send mes- 
sages after it has called server_ending. 


void server_ending() 


{ 


int 


int 


#if£ DEBUG_TRACE 
printf("%d :- server_ending()\n", getpid()); 
#endif 





(void)msgctl(serv_qid, IPC_RMID, 0); 
(void)msgctl(cli_qid, IPC_RMID, 0); 


serv_qid = -1; 

Ci 

The server read function reads a message of any type (that is, from any client) from the queue, 
and it returns the data part (ignoring the type) of the message: 

read_request_from_client (message_db_t *rec_ptr) 

struct msg_passed my_msg; 


#if DEBUG_TRACE 
printf("%d :- read_request_from_client()\n", getpid()); 





#endif 

if (msgrcv(serv_qid, (void *)&my_msg, sizeof(*rec_ptr), 0, 0) == -1) { 
return(0); 

} 

*rec_ptr = my_msg.real_message; 

return(1); 


Sending a response uses the client process ID that was stored in the request to address the message: 
send_resp_to_client (const message_db_t mess_to_send) 


struct msg_passed my_msg; 
#if£ DEBUG_TRACE 

printf("%d :- send_resp_to_client()\n", getpid()); 
#endif 





my_msg.real_message = mess_to_send; 
my_msg.msg_key = mess_to_send.client_pid; 


if (msgsnd(cli_qid, (void *)&my_msg, sizeof(mess_to_send), 0) == -1) { 
return (0); 
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} 


return(1); 


Revising the Client Functions 


Next, you perform the changes to the client functions. 


1. When the client starts, it needs to find the server and client queue identifiers. The client doesn’t 


create the queues. This function will fail if the server isn’t running, because the message queues 
won't exist. 


int client_starting() 
{ 
#i1£ DEBUG_TRACE 
printf("%d :- client_starting\n", getpid()); 
#endif 


serv_qid = msgget((key_t) SERVER_MQUEUE, 0666); 
if (serv_qid == -1) return(0); 








cli_qid = msgget((key_t)CLIENT_MQUEUE, 0666); 
mie ((ellak_avel 2S =i) sasieneia (0) ¢ 
return(1); 


2. As with the server, when the client ends, you set your file-scope variables to illegal values. This 
will catch any bugs where the client attempts to send messages after it has called client_ending. 


void client_ending() 
{ 
#i1£ DEBUG_TRACE 


printf("sd :- client_ending()\n", getpid()); 
#endif 


serv_qid = -1; 
Gilsi_yeaiel = ile 


3. Tosenda message to the server, store the data inside your structure. Notice that you must set 
the message key. Because 0 is an illegal value for the key, leaving the key undefined would 


mean that it takes an (apparently) random value, so this function could occasionally fail if the 
value happens to be 0. 


int send_mess_to_server(message_db_t mess_to_send) 


struct msg_passed my_msg; 
#1£ DEBUG_TRACE 


printf("%d :- send_mess_to_server()\n", getpid()); 
#endif 


my_msg.real_message = mess_to_send; 
my_msg.msg_key = mess_to_send.client_pid; 
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if (msgsnd(serv_qid, (void *)&my_msg, sizeof(mess_to_send), 0) == -1) { 
perror("Message send failed"); 
return (0); 

} 

return (1) ; 


When the client retrieves a message from the server, it uses its process ID to receive only mes- 
sages addressed to itself, ignoring any messages for other clients. 


read_resp_from_server(message_db_t *rec_ptr) 


struct msg_passed my_msg; 
#if£ DEBUG_TRACE 





printf("%d :- read_resp_from_server()\n", getpid()); 

#endif 

if (msgrcv(cli_gid, (void *)&my_msg, sizeof(*rec_ptr), getpid(), 0) == -1) { 
return (0) ; 


} 
*rec_ptr = my_msg.real_message; 
return(1); 


To retain complete compatibility with pipe_imp.c, you need to define four extra functions. In 
your new program, however, the functions are empty. The operations they implemented when 
using pipes are simply not needed anymore. 


start_resp_to_client(const message_db_t mess_to_send) 


return(1); 


void end_resp_to_client (void) 


{ 
} 


int 


{ 


} 


start_resp_from_server (void) 


return(1); 


void end_resp_from_server (void) 


{ 
} 


You can now simply start the server, which does the actual data storage and retrieval, in the background, 
and then run the client application to connect to it using messages. 


All you have had to do here is replace the interface functions from Chapter 11 with a different imple- 
mentation using message queues. The conversion of the application to message queues illustrates the 
power of IPC message queues, because you require fewer functions than the pipes application, and even 
those functions that you do need are much simpler than they were in the earlier implementation. 
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IPC Status Commands 


Although they’re not required for X/Open compliance, most Linux systems provide a set of commands 
that allow command-line access to IPC information, and to tidy up stray IPC facilities. These are the 
ipcs and ipcrm commands, which are very useful when you're developing programs. 


One of the irritations of the IPC facilities is that a poorly written program, or a program that fails for 
some reason, can leave its IPC resources (such as data in a message queue) loitering on the system long 
after the program completes. This can cause a new invocation of the program to fail, because the pro- 
gram expects to start with a clean system, but actually finds some leftover resource. The status (ipcs) 
and remove (ipcrm) commands provide a way of checking and tidying up IPC facilities. 


Displaying Semaphore Status 


To examine the state of semaphores on the system, use the ipcs -s command. If any semaphores are 
present, the output will have this form: 


$ ./ipes -s 
ea Semaphore Arrays -------- 
key semid owner perms nsems 


0x4d00dfla 768 rick 666 1 


You can use the ipcrm command to remove any semaphores accidentally left by programs. To delete the 
preceding semaphore, the command (on Linux) is 


$ ./ipcrm -s 768 
Some much older Linux systems used to use a slightly different syntax: 
$ ./ipcrm sem 768 


but that style is now rare. Check the manual pages for your system to see which format is valid on your 
particular system. 


Displaying Shared Memory Status 


Like semaphores, many systems provide command-line programs for accessing the details of shared 
memory. These are ipcs -mand ipcrm -m <id> (or ipcrm shm <id>). 


Here’s some sample output from ipcs -m: 
$ ipcs -m 


-2n Shared Memory Segments -------- 
key shmid owner perms bytes nattch status 
0x00000000 384 rick 666 4096 2 dest 


This shows a single shared memory segment of 4 KB attached by two processes. 
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The ipcrm -m <id> command allows shared memory to be removed. This is sometimes useful when a 
program has failed to tidy up shared memory. 


Displaying Message Queue Status 
For message queues the commands are ipcs -qand ipcrm -q <id>(oripcrm msg <id>). 
Here’s some sample output from ipcs -q: 
$ ipcs -q 
E Message Queues -------- 
key msqid owner perms used-bytes messages 
0x000004d2 3384 rick 666 2048 2 


This shows two messages, with a total size of 2,048 bytes in a message queue. 


The ipcrm -q <id> command allows a message queue to be removed. 


Summary 


In this chapter, you looked at the three inter-process communication facilities that first became widely 
available in UNIX System V.2 and have been available in Linux from the early distributions. These facili- 
ties are semaphores, shared memory, and message queues. You’ve seen the sophisticated functionality 
that they offer and how, once these functions are understood, they offer a powerful solution to many 
inter-process communication requirements. 
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In this chapter, you look at yet another method of process communication, but one with a crucial 
difference from those we’ve discussed in Chapters 13 and 14. Until now, all the facilities we've dis- 
cussed have relied on shared resources on a single computer system. The resource varies; it can be 
file system space, shared physical memory, or message queues, but only processes running on a 
single machine can use them. 


The Berkeley versions of UNIX introduced a new communication tool, the socket interface, which is 
an extension of the concept of a pipe, covered in Chapter 13. Socket interfaces are available on Linux. 
You can use sockets in much the same way as pipes, but they include communication across a net- 
work of computers. A process on one machine can use sockets to communicate with a process on 
another, which allows for client/server systems that are distributed across a network. Sockets may 
also be used between processes on the same machine. 


Also, the sockets interface has been made available for Windows via a publicly available specifica- 
tion called Windows Sockets, or WinSock. Windows socket services are provided by a Winsock.d11 
system file. So, Windows programs can communicate across a network to Linux and UNIX com- 
puters and vice versa, thus implementing client/server systems. Although the programming inter- 
face for WinSock isn’t quite the same as UNIX sockets, it still has sockets as its basis. 


We can’t cover the extensive Linux networking capabilities in a single chapter, so you'll find here a 
description of the principal programmatic networking interfaces. These should allow you to write 
your own network programs. Specifically, we look at the following: 

How a socket connection operates 

Socket attributes, addresses, and communications 


Network information and the Internet daemon (inetd/xinetd) 





Ooveo ovo 


Clients and servers 
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What Is a Socket? 


A socket is a communication mechanism that allows client/server systems to be developed either locally, 
on a single machine, or across networks. Linux functions such as printing, connecting to databases, and 

serving web pages as well as network utilities such as rlogin for remote login and ftp for file transfer 

usually use sockets to communicate. 


Sockets are created and used differently from pipes because they make a clear distinction between client 
and server. The socket mechanism can implement multiple clients attached to a single server. 


Socket Connections 


You can think of socket connections as telephone calls into a busy building. A call comes into an organiza- 
tion and is answered by a receptionist who puts the call through to the correct department (the server 
process) and from there to the right person (the server socket). Each incoming call (client) is routed to an 
appropriate end point and the intervening operators are free to deal with further calls. Before you look at 
the way socket connections are established in Linux systems, you need to understand how they operate 
for socket applications that maintain a connection. 


First, a server application creates a socket, which like a file descriptor is a resource assigned to the server 
process and that process alone. The server creates it using the system call socket, and it can’t be shared 
with other processes. 


Next, the server process gives the socket a name. Local sockets are given a filename in the Linux file sys- 
tem, often to be found in /tmp or /usr/tmp. For network sockets, the filename will be a service identi- 
fier (port number /access point) relevant to the particular network to which the clients can connect. This 
identifier allows Linux to route incoming connections specifying a particular port number to the correct 
server process. For example, a web server typically creates a socket on port 80, an identifier reserved for 
the purpose. Web browsers know to use port 80 for their HTTP connections to web sites the user wants 
to read. A socket is named using the system call bind. The server process then waits for a client to con- 
nect to the named socket. The system call, 1isten, creates a queue for incoming connections. The server 
can accept them using the system call accept. 


When the server calls accept, a new socket is created that is distinct from the named socket. This 

new socket is used solely for communication with this particular client. The named socket remains for 
further connections from other clients. If the server is written appropriately, it can take advantage of 
multiple connections. A web server will do this so that it can serve pages to many clients at once. For a 
simple server, further clients wait on the listen queue until the server is ready again. 


The client side of a socket-based system is more straightforward. The client creates an unnamed socket 
by calling socket. It then calls connect to establish a connection with the server by using the server’s 


named socket as an address. 


Once established, sockets can be used like low-level file descriptors, providing two-way data 
communications. 
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Here’s an example of a very simple socket client program, client1.c. It creates an unnamed socket and 
connects it to a server socket called server_socket. We cover the details of the socket system call a lit- 


tle later, after we’ve discussed some addressing issues. 
1. — Make the necessary includes and set up the variables: 


#include <sys/types.h> 
#include <sys/socket.h> 
#include <stdio.h> 
#include <sys/un.h> 
#include <unistd.h> 
#include <stdlib.h> 


int main() 
{ 
int sockfd; 
int len; 
struct sockaddr_un address; 
int result; 
Chath sha: 


2. Create a socket for the client: 


sockfd = socket (AF_UNIX, SOCK_STREAM, 0); 





3. Name the socket as agreed with the server: 
address.sun_family = AF_UNIX; 
strcpy(address.sun_path, "server_socket") ; 


len = sizeof (address); 


4. Connect your socket to the server’s socket: 


result = connect(sockfd, (struct sockaddr *)&address, 


aesti eE il) { 
perror("oops: client1") ; 
exit (1); 


5. You can now read and write via sockfd: 


write(sockfd, &ch, 1); 

read(sockfd, &ch, 1); 

printf("char from server = %c\n", ch); 
close(sockfd) ; 

exit (0); 


len) ; 
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This program fails when you run it because you haven't yet created the server-side named socket. (The 
exact error message may differ from system to system.) 


$ 


.-/client1 


oops: clientl: No such file or directory 


$ 


Try It Out A Simple Local Server 


Here’s a very simple server program, server1 .c, that accepts connections from the client. It creates the 
server socket, binds it to a name, creates a listen queue, and accepts connections. 
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Make the necessary includes and set up the variables: 


#include <sys/types.h> 
#include <sys/socket .h> 
#include <stdio.h> 
#include <sys/un.h> 
#include <unistd.h> 
#include <stdlib.h> 


int main() 


{ 


int server_sockfd, client_sockfd; 
int server_len, client_len; 

struct sockaddr_un server_address; 
struct sockaddr_un client_address; 


Remove any old sockets and create an unnamed socket for the server: 


unlink ("server_socket"); 
server_sockfd = socket (AF_UNIX, SOCK_STREAM, 0); 





Name the socket: 


server_address.sun_family = AF_UNIX; 

strcpy(server_address.sun_path, "server_socket"); 

server_len = sizeof (server_address) ; 

bind(server_sockfd, (struct sockaddr *)&server_address, server_len) ; 


Create a connection queue and wait for clients: 
listen(server_sockfd, 5); 
while(1) { 


Elavee Clap 


printf ("server waiting\n"); 
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5. Accept a connection: 


client_len = sizeof (client_address); 
client_sockfd = accept (server_sockfd, 
(struct sockaddr *)&client_address, &client_len) ; 


6. Read and write to client on client_sockfd: 


read(client_sockfd, &ch, 1); 
SENEE 

write(client_sockfd, &ch, 1); 
close(client_sockfd); 


How It Works 


The server program in this example can serve only one client at a time. It just reads a character from the 
client, increments it, and writes it back. In more sophisticated systems, where the server has to perform 
more work on the client’s behalf, this wouldn’t be acceptable, because other clients would be unable to 
connect until the server had finished. You'll see a couple of ways to allow multiple connections later. 


When you run the server program, it creates a socket and waits for connections. If you start it in the 
background so that it runs independently, you can then start clients in the foreground. 


$ ./serverl & 
[1] 1094 
$ server waiting 


As it waits for connections, the server prints a message. In the preceding example, the server waits for a 
file system socket and you can see it with the normal 1s command. 


Remember that it’s good practice to remove a socket when you've finished with it, even if the 
program terminates abnormally via a signal. This keeps the file system from getting cluttered with 
unused files. 


$ ls -1F server_socket 
SrwWXr-xr-x 1 neil users 0 2007-06-23 11:41 server_socket= 


The device type is “socket,” shown by the s at the front of the permissions and the = at the end of the 
name. The socket has been created just as an ordinary file would be, with permissions modified by 
the current umask. If you use the ps command, you can see the server running in the background. It’s 
shown sleeping (STAT is S$) and is therefore not consuming CPU resources. 


$ ps 1x 
F UID PID PPID PRI NI VSZ RSS WCHAN STAT TTY TIME COMMAND 
0 1000 23385 10689 17 O 1424 312 361800 S pts/1 0:00 ./serverl 
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Now, when you run the client program, you are successful in connecting to the server. Because the 
server socket exists, you can connect to it and communicate with the server. 


$ ./client1 
server waiting 
char from server = B 


$ 


The output from the server and the client get mixed on the terminal, but you can see that the server has 
received a character from the client, incremented it, and returned it. The server then continues and waits 
for the next client. If you run several clients together, they will be served in sequence, although the out- 
put you see may be more mixed up. 


$ ./client1 & ./client1 & ./client1 & 


[2] 23412 
[3] 23413 
[4] 23414 


server waiting 

char from server = B 
server waiting 
char from server 
server waiting 
char from server 
server waiting 
[2] Done client1 
[3]- Done client1 
[4]+ Done client1 
$ 


ll 
w 


Il 
w 


Socket Attributes 


To fully understand the system calls used in this example, you need to learn a little about UNIX 
networking. 


Sockets are characterized by three attributes: domain, type, and protocol. They also have an address used 
as their name. The formats of the addresses vary depending on the domain, also known as the protocol 
family. Each protocol family can use one or more address families to define the address format. 


Socket Domains 


Domains specify the network medium that the socket communication will use. The most common socket 
domain is AF_INET, which refers to Internet networking that’s used on many Linux local area networks 
and, of course, the Internet itself. The underlying protocol, Internet Protocol (IP), which only has one address 
family, imposes a particular way of specifying computers on a network. This is called the IP address. 


The “next generation” Internet Protocol, IPv6, has been designed to overcome some of the problems 
with the standard IP, notably the limited number of addresses that are available. IPv6 uses a different 
socket domain, AF_INET6, and a different address format. It is expected to eventually replace IP, but 
this process will take many years. Although there are implementations of IPv6 for Linux, it is beyond 
the scope of this book. 
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Although names almost always refer to networked machines on the Internet, these are translated into 
lower-level IP addresses. An example IP address is 192.168.1.99. All IP addresses are represented by four 
numbers, each less than 256, a so-called dotted quad. When a client connects across a network via sockets, 
it needs the IP address of the server computer. 


There may be several services available at the server computer. A client can address a particular service on a 
networked machine by using an IP port. A port is identified within the system by assigning a unique 16-bit 
integer and externally by the combination of IP address and port number. The sockets are communication 
end points that must be bound to ports before communication is possible. 


Servers wait for connections on particular ports. Well-known services have allocated port numbers that 
are used by all Linux and UNIX machines. These are usually, but not always, numbers less than 1024. 
Examples are the printer spooler (515), rlogin (513), £tp (21), and httpd (80). The last of these is the 
standard port for web servers. Usually, port numbers less than 1024 are reserved for system services and 
may only be served by processes with superuser privileges. X/Open defines a constant in netdb.h, 
IPPORT_RESERVED, to stand for the highest reserved port number. 





Because there is a standard set of port numbers for standard services, computers can easily connect to each 
other without having to figure out the correct port. Local services may use nonstandard port addresses. 


The domain in the first example is the UNIX file system domain, AF_UNIX, which can be used by sockets 
based on a single computer that perhaps isn’t networked. When this is so, the underlying protocol is 

file input/output and the addresses are filenames. The address that you used for the server socket was 
server_socket, which you saw appear in the current directory when you ran the server application. 


Other domains that might be used include AF_1So for networks based on ISO standard protocols and 
AF_XNS for the Xerox Network System. We won’t cover these here. 


Socket Types 


A socket domain may have a number of different ways of communicating, each of which might have 
different characteristics. This isn’t an issue with AF_UNIX domain sockets, which provide a reliable two- 
way communication path. In networked domains, however, you need to be aware of the characteristics 
of the underlying network and how different communication mechanisms are affected by them. 


Internet protocols provide two communication mechanisms with distinct levels of service: streams 
and datagrams. 


Stream Sockets 


Stream sockets (in some ways similar to standard input/output streams) provide a connection that is a 
sequenced and reliable two-way byte stream. Thus, data sent is guaranteed not to be lost, duplicated, or 
reordered without an indication that an error has occurred. Large messages are fragmented, transmitted, 
and reassembled. This is similar to a file stream, which also accepts large amounts of data and splits it 
up for writing to the low-level disk in smaller blocks. Stream sockets have predictable behavior. 


Stream sockets, specified by the type SOCK_STREAM, are implemented in the AF_INET domain by TCP/IP 


connections. They are also the usual type in the AF_UNIX domain. We concentrate on SOCK_STREAM sockets 
in this chapter because they are more commonly used in programming network applications. 
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TCP/IP stands for Transmission Control Protocol/Internet Protocol. IP is the low-level protocol 

for packets that provides routing through the network from one computer to another. TCP provides 
sequencing, flow control, and retransmission to ensure that large data transfers arrive with all of the 
data present and correct or with an appropriate error condition reported. 


Datagram Sockets 


In contrast, a datagram socket, specified by the type SOCK_DGRAM, doesn’t establish and maintain a con- 
nection. There is also a limit on the size of a datagram that can be sent. It’s transmitted as a single network 
message that may get lost, duplicated, or arrive out of sequence — ahead of datagrams sent after it. 





Datagram sockets are implemented in the AF_INET domain by UDP/IP connections and provide an 
unsequenced, unreliable service. (UDP stands for User Datagram Protocol.) However, they are relatively 
inexpensive in terms of resources, because network connections need not be maintained. They’re fast 
because there is no associated connection setup time. 


Datagrams are useful for “single-shot” inquiries to information services, for providing regular status 
information, or for performing low-priority logging. They have the advantage that the death of a server 
doesn’t unduly inconvenience a client and would not require a client restart. Because datagram-based 
servers usually retain no connection information, they can be stopped and restarted without disturbing 
their clients. 


For now, we leave the topic of datagrams; see the “Datagrams” section near the end of this chapter for 
more information. 


Socket Protocols 


Where the underlying transport mechanism allows for more than one protocol to provide the requested 
socket type, you can select a specific protocol for a socket. In this chapter, we concentrate on UNIX net- 
work and file system sockets, which don’t require you to choose a protocol other than the default. 


Creating a Socket 


The socket system call creates a socket and returns a descriptor that can be used for accessing the socket. 


#include <sys/types.h> 
#include <sys/socket.h> 


int socket(int domain, int type, int protocol); 
The socket created is one end point of a communication channel. The domain parameter specifies the 
address family, the type parameter specifies the type of communication to be used with this socket, and 


protocol specifies the protocol to be employed. 


Domains include those in the following table: 


Domain Description 
AF_UNIX UNIX internal (file system sockets) 
AF_INET ARPA Internet protocols (UNIX network sockets) 
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Domain Description 

AF_ISO ISO standard protocols 

AF_NS Xerox Network Systems protocols 
AF_IPX Novell IPX protocol 
AF_APPLETALK Appletalk DDS 


The most common socket domains are AF_UNIX, which is used for local sockets implemented via the 
UNIX and Linux file systems, and AF_INET, which is used for UNIX network sockets. The AF_INET 
sockets may be used by programs communicating across a TCP/IP network including the Internet. The 
Windows Winsock interface also provides access to this socket domain. 





The socket parameter type specifies the communication characteristics to be used for the new socket. 
Possible values include SOCK_STREAM and SOCK_DGRAM. 


SOCK_STREAM is a sequenced, reliable, connection-based two-way byte stream. For an AF_INET domain 
socket, this is provided by default by a TCP connection that is established between the two end points of 
the stream socket when it’s connected. Data may be passed in both directions along the socket connec- 
tion. The TCP protocols include facilities to fragment and reassemble long messages and to retransmit 
any parts that may be lost in the network. 


SOCK_DGRAM is a datagram service. You can use this socket to send messages of a fixed (usually small) max- 
imum size, but there’s no guarantee that the message will be delivered or that messages won’t be reordered 
in the network. For AF_INET sockets, this type of communication is provided by UDP datagrams. 


The protocol used for communication is usually determined by the socket type and domain. There is nor- 
mally no choice. The protocol parameter is used where there is a choice. 0 selects the default protocol, 
which is used in all the examples in this chapter. 


The socket system call returns a descriptor that is in many ways similar to a low-level file descriptor. 
When the socket has been connected to another end-point socket, you can use the read and write sys- 
tem calls with the descriptor to send and receive data on the socket. The close system call is used to 
end a socket connection. 


Socket Addresses 


Each socket domain requires its own address format. For an AF_UNIX socket, the address is described by 
a structure, sockaddr_un, defined in the sys/un.h include file. 


struct sockaddr_un { 


sa_family t sun_family; /* AF_UNIX */ 
char sun_path[]; /* pathname */ 
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So that addresses of different types may be passed to the socket-handling system calls, each address for- 
mat is described by a similar structure that begins with a field (in this case, sun_family) that specifies 
the address type (the socket domain). In the AF_UNIX domain, the address is specified by a filename in 
the sun_path field of the structure. 


On current Linux systems, the type sa_family_t, defined by X/Open as being declared in sys/un.h, 
is taken to be a short. Also, the pathname specified in sun_path is limited in size (Linux specifies 108 
characters; others may use a manifest constant such as UNIX_MAX_PATH). Because address structures 
may vary in size, many socket calls require or provide as an output a length to be used for copying the 
particular address structure. 


In the AF_INET domain, the address is specified using a structure called sockaddr_in, defined in 
netinet/in.h, which contains at least these members: 


struct sockaddr_in { 


short int sin_family; /* AF_INET */ 
unsigned short int sin_port; /* Port number */ 
struct in_addr sin_addr; /* Internet address */ 


The IP address structure, in_addr, is defined as follows: 


struct in_addr { 
unsigned long int s_addr; 
}; 





The four bytes of an IP address constitute a single 32-bit value. An AF_INET socket is fully described 
by its domain, IP address, and port number. From an application’s point of view, all sockets act like file 
descriptors and are addressed by a unique integer value. 


Naming a Socket 


To make a socket (as created by a call to socket) available for use by other processes, a server program 
needs to give the socket a name. Thus, AF_UNIX sockets are associated with a file system pathname, as 
you saw in the server1 example. AF_INET sockets are associated with an IP port number. 


#include <sys/socket.h> 

int bind(int socket, const struct sockaddr *address, size_t address_len); 
The bind system call assigns the address specified in the parameter, address, to the unnamed 
socket associated with the file descriptor socket. The length of the address structure is passed as 


address_len. 


The length and format of the address depend on the address family. A particular address structure 
pointer will need to be cast to the generic address type (struct sockaddr *) in the call to bind. 


On successful completion, bind returns 0. If it fails, it returns -1 and sets errno to one of the follow- 
ing values: 
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Errno Value Description 

EBADF The file descriptor is invalid. 

ENOTSOCK The file descriptor doesn’t refer to a socket. 

EINVAL The file descriptor refers to an already-named socket. 
EADDRNOTAVAIL The address is unavailable. 

EADDRINUSE The address has a socket bound to it already. 


There are some more values for AF_UNIX sockets: 





Errno value Description 
EACCESS Can't create the file system name due to permissions. 
ENOTDIR, ENAMETOOLONG Indicates a poor choice of filename. 


Creating a Socket Queue 


To accept incoming connections on a socket, a server program must create a queue to store pending 
requests. It does this using the 1isten system call. 


#include <sys/socket.h> 
int listen(int socket, int backlog); 


A Linux system may limit the maximum number of pending connections that may be held in a queue. 
Subject to this maximum, listen sets the queue length to backlog. Incoming connections up to this 
queue length are held pending on the socket; further connections will be refused and the client’s connec- 
tion will fail. This mechanism is provided by listen to allow incoming connections to be held pending 
while a server program is busy dealing with a previous client. A value of 5 for backlog is very common. 


The listen function will return 0 on successd returns 0. If it fails, it returns -1 and sets errno to one of the follow- 
ing values: 


616 


Chapter 15: Sockets 


Errno Value Description 

EBADF The file descriptor is invalid. 

ENOTSOCK The file descriptor doesn’t refer to a socket. 

EINVAL The file descriptor refers to an already-named socket. 
EADDRNOTAVAIL The address is unavailable. 

EADDRINUSE The address has a socket bound to it already. 


There are some more values for AF_UNIX sockets: 





Errno value Description 
EACCESS Can't create the file system name due to permissions. 
ENOTDIR, ENAMETOOLONG Indicates a poor choice of filename. 


Creating a Socket Queue 


To accept incoming connections on a socket, a server program must create a queue to store pending 
requests. It does this using the 1isten system call. 


#include <sys/socket.h> 


int listen(int socket, int backlog); 


A Linux system may limit the maximum number of pending connections that may be held in a queue. 
Subject to this maximum, listen sets the queue length to backlog. Incoming connections up to this 
queue length are held pending on the socket; further connections will be refused and the client’s connec- 
tion will fail. This mechanism is provided by listen to allow incoming connections to be held pending 
while a server program is busy dealing with a previous client. A value of 5 for backlog is very common. 





The listen function will return 0 on success or -1 on error. Errors include EBADF, EINVAL, and ENOT- 
SOCK, as for the bind system call. 


Accepting Connections 


Once a server program has created and named a socket, it can wait for connections to be made to the 
socket by using the accept system call. 


#include <sys/socket.h> 


int accept(int socket, struct sockaddr *address, size_t *address_len); 
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The accept system call returns when a client program attempts to connect to the socket specified by the 
parameter socket. The client is the first pending connection from that socket’s queue. The accept func- 
tion creates a new socket to communicate with the client and returns its descriptor. The new socket will 
have the same type as the server listen socket. 


The socket must have previously been named by a call to bind and had a connection queue allocated by 
listen. The address of the calling client will be placed in the sockaddr structure pointed to by address. 
A null pointer may be used here if the client address isn’t of interest. 


The address_len parameter specifies the length of the client structure. If the client address is longer than 
this value, it will be truncated. Before calling accept, address_len must be set to the expected address 
length. On return, address_len will be set to the actual length of the calling client’s address structure. 


If there are no connections pending on the socket’s queue, accept will block (so that the program won’t 
continue) until a client does make connection. You can change this behavior by using the O_NONBLOCK 
flag on the socket file descriptor, using the £cnt1 function in your code like this: 


int flags = fcentl(socket, F_GETFL, 0); 


fentl(socket, F_SETFL, O_NONBLOCK| flags); 


The accept function returns a new socket file descriptor when there is a client connection pending or 

-1 on error. Possible errors are similar to those for bind and listen, with the addition of EWOULDBLOCK, 
where O_NONBLOCK has been specified and there are no pending connections. The error EINTR will occur 
if the process is interrupted while blocked in accept. 


Requesting Connections 


Client programs connect to servers by establishing a connection between an unnamed socket and the 
server listen socket. They do this by calling connect. 


#include <sys/socket.h> 
int connect (int socket, const struct sockaddr *address, size_t address_len); 


The socket specified by the parameter socket is connected to the server socket specified by the parame- 
ter address, which is of length address_len. The socket must be a valid file descriptor obtained by a 
call to socket. 


If it succeeds, connect returns 0, and -1 is returned on error. Possible errors this time include the 
following: 


Errno Value Description 

EBADF An invalid file descriptor was passed in socket. 
EALREADY A connection is already in progress for this socket. 
ETIMEDOUT A connection timeout has occurred. 

ECONNREFUSED The requested connection was refused by the server. 
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If the connection can’t be set up immediately, connect will block for an unspecified timeout period. Once 
this timeout has expired, the connection will be aborted and connect will fail. However, if the call to con- 
nect is interrupted by a signal that is handled, the connect call will fail (with errno set to EINTR), but the 
connection attempt won’t be aborted — it will be set up asynchronously, and the program will have to 
check later to see if the connection was successful. 





As with accept, the blocking nature of connect can be altered by setting the O_NONBLOCK flag on the 
file descriptor. In this case, if the connection can’t be made immediately, connect will fail with errno 
set to EINPROGRESS and the connection will be made asynchronously. 





Though asynchronous connections can be tricky to handle, you can use a call to select on the socket 
file descriptor to check that the socket is ready for writing. We cover select later in this chapter. 


Closing a Socket 


You can terminate a socket connection at the server and client by calling close, just as you would for low- 
level file descriptors. You should always close the socket at both ends. For the server, you should do this 
when read returns zero. Note that the close call may block if the socket has untransmitted data, is of a 
connection-oriented type, and has the SOCK_LINGER option set. You learn about setting socket options 
later in this chapter. 


Socket Communications 


Now that we have covered the basic system calls associated with sockets, let’s take a closer look at the 
example programs. You'll try to convert them to use a network socket rather than a file system socket. The 
file system socket has the disadvantage that, unless the author uses an absolute pathname, it’s created in 
the server program’s current directory. To make it more generally useful, you need to create it in a globally 
accessible directory (such as /tmp) that is agreed between the server and its clients. For network sockets, 
you need only choose an unused port number. 


For the example, select port number 9734. This is an arbitrary choice that avoids the standard services 
(you can’t use port numbers below 1024 because they are reserved for system use). Other port numbers 
are often listed, with the services provided on them, in the system file /etc/services. When you’re 
writing socket-based applications, always choose a port number not listed in this configuration file. 





Be aware that there is a deliberate error in the programs client2.c and server2.c 
that you will fix in client3.c and server3 .c. Please do not use the code from 
client2.c and server2.c in your own programs. 








You'll run your client and server across a local network, but network sockets are not only useful on a 
local area network; any machine with an Internet connection (even a modem dial-up) can use network 
sockets to communicate with others. You can even use a network-based program on a stand-alone UNIX 
computer because a UNIX computer is usually configured to use a loopback network that contains only 
itself. For illustration purposes, this example uses this loopback network, which can also be useful for 
debugging network applications because it eliminates any external network problems. 
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The loopback network consists of a single computer, conventionally called localhost, with a standard 
IP address of 127.0.0.1. This is the local machine. You'll find its address listed in the network hosts file, 
/etc/hosts, with the names and addresses of other hosts on shared networks. 


Each network with which a computer communicates has a hardware interface associated with it. A com- 
puter may have different network names on each network and certainly will have different IP addresses. 
For example, Neil’s machine tilde has three network interfaces and therefore three addresses. These 
are recorded in /etc/hosts as follows: 





12°70 3:0). localhost # Loopback 
192.168.1.1 tilde.localnet # Local, private Ethernet 
158.152.xX.X tilde.demon.co.uk # Modem dial-up 


The first is the simple loopback network, the second is a local area network accessed via an Ethernet 
adapter, and the third is the modem link to an Internet service provider. You can write a network socket- 
based program to communicate with servers accessed via any of these interfaces without alteration. 


Try It Out Network Client 


Here’s a modified client program, client2.c, to connect to a network socket via the loopback network. 
It contains a subtle bug concerned with hardware dependency, but we'll discuss that later in this chapter. 


1. Make the necessary includes and set up the variables: 


#include <sys/types.h> 
#include <sys/socket .h> 
#include <stdio.h> 
#include <netinet/in.h> 
#include <arpa/inet.h> 
#include <unistd.h> 
#include <stdlib.h> 


int main() 





int sockfd; 

int len; 

struct sockaddr_in address; 
int result; 

char ch = 'A'; 


2. Create a socket for the client: 
sockfd = socket (AF_INET, SOCK_STREAM, 0); 

3. Name the socket, as agreed with the server: 
address.sin_family = AF_INET; 
address.sin_addr.s_addr = inet_addr("127.0.0.1"); 


address.sin_port = 9734; 
len = sizeof (address); 
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The rest of this program is the same as client1.c from earlier in this chapter. When you run this version, 
it fails to connect because there isn’t a server running on port 9734 on this machine. 


$ ./client2 
oops: client2: Connection refused 


$ 


How It Works 


The client program used the sockaddr_in structure from the include file netinet/in.h to specify an 
AF_INET address. It tries to connect to a server on the host with IP address 127.0.0.1. It uses a function, 
inet_addr, to convert the text representation of an IP address into a form suitable for socket addressing. 
The manual page for inet has more information on other address translation functions. 


Try It Out Network Server 


You also need to modify the server program to wait for connections on your chosen port number. Here’s 
a modified server: server2.c. 


1. Make the necessary includes and set up the variables: 


#include <sys/types.h> 
#include <sys/socket.h> 
#include <stdio.h> 
#include <netinet/in.h> 
#include <arpa/inet.h> 
#include <unistd.h> 
#include <stdlib.h> 


int main() 

{ 
int server_sockfd, client_sockfd; 
int server_len, client_len; 
struct sockaddr_in server_address; 
struct sockaddr_in client_address; 


2. Create an unnamed socket for the server: 
server_sockfd = socket (AF_INET, SOCK_STREAM, 0); 


3. Name the socket: 





server_address.sin_family = AF_INET; 

server_address.sin_addr.s_addr = inet_addr("127.0.0.1"); 
server_address.sin_port = 9734; 

server_len = sizeof (server_address) ; 

bind(server_sockfd, (struct sockaddr *)&server_address, server_len); 


From here on, the listing follows server1 .c exactly. Running client2 and server2 will show the 
same behavior you saw earlier with client1 and server1. 
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How It Works 


The server program creates an AF_INET domain socket and arranges to accept connections on it. The 
socket is bound to your chosen port. The address specified determines which computers are allowed to 
connect. By specifying the loopback address, as in the client program, you are restricting communica- 
tions to the local machine. 


If you want to allow the server to communicate with remote clients, you must specify a set of IP addresses 
that you are willing to allow. You can use the special value, INADDR_ANY, to specify that you'll accept con- 
nections from all of the interfaces your computer may have. If you chose to, you could distinguish between 
different network interfaces to separate, for example, internal Local Area Network and external Wide Area 
Network connections. INADDR_ANY is a 32-bit integer value that you can use in the sin_addr .s_addr field 
of the address structure. However, you have a problem to resolve first. 


Host and Network Byte Ordering 


When we run these versions of the server and client programs on an Intel processor-based Linux 
machine, we can see the network connections by using the netstat command. This command will also 
be available on most UNIX systems configured for networking. It shows the client/server connection 
waiting to close down. The connection closes down after a small timeout. (Again, the exact output may 
vary among different versions of Linux.) 


$ ./server2 & ./client2 

[3] 23770 

server waiting 

server waiting 

char from server = B 

$ netstat -A inet 

Active Internet connections (w/o servers) 

Proto Recv-Q Send-Q Local Address Foreign Address (State) User 
tcp 1 0 localhost:1574 localhost:1174 TIME_WAIT root 








Before you try out further examples in this book, be sure to terminate running exam- 
ple server programs, because they will compete to accept connections from clients 
and you'll see confusing results. You can kill them all (including ones covered later 
in the chapter) with the following command: 


killall serverl server2 server3 server4 server5 











You can see the port numbers that have been assigned to the connection between the server and the 
client. The local address shows the server, and the foreign address is the remote client. (Even though it’s 
on the same machine, it’s still connected over a network.) To ensure that all sockets are distinct, these 
client ports are typically different from the server listen socket and unique to the computer. 
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However, the local address (the server socket) is given as 1574 (or you may see mvel-1mas a service name), 
but the port chosen in the example is 9734. Why are they different? The answer is that port numbers and 
addresses are communicated over socket interfaces as binary numbers. Different computers use different 
byte ordering for integers. For example, an Intel processor stores the 32-bit integer as four consecutive bytes 
in memory in the order 1-2-3-4, where 1 is the most significant byte. IBM PowerPC processors would store 
the integer in the byte order 4-3-2-1. If the memory used for integers were simply copied byte-by-byte, the 
two different computers would not be able to agree on integer values. 


To enable computers of different types to agree on values for multibyte integers transmitted over a net- 
work, you need to define a network ordering. Client and server programs must convert their internal 
integer representation to the network ordering before transmission. They do this by using functions 
defined in netinet/in.h. These are 


#include <netinet/in.h> 

unsigned long int htonl(unsigned long int hostlong) ; 
unsigned short int htons (unsigned short int hostshort) ; 
unsigned long int ntohl(unsigned long int netlong); 


unsigned short int ntohs (unsigned short int netshort) ; 


These functions convert 16-bit and 32-bit integers between native host format and the standard network 
ordering. Their names are abbreviations for conversions — for example, “host to network, long” (hton1) 
and “host to network, short” (htons). For computers where the native ordering is the same as network 
ordering, these represent null operations. 


To ensure correct byte ordering of the 16-bit port number, your server and client need to apply these 
functions to the port address. The change to server3 .c is 


server_address.sin_addr.s_addr = htonl(INADDR_ANY) ; 
server_address.sin_port = htons (9734); 


You don’t need to convert the function call, inet_addr ("127.0.0.1"), because inet_addr is defined 
to produce a result in network order. The change to client3 .c is 


address.sin_port = htons (9734); 
The server has also been changed to allow connections from any IP address by using INADDR_ANY. 


Now, when you run server3 and client3, you see the correct port being used for the local connection. 


$ netstat 

Active Internet connections 

Proto Recv-Q Send-Q Local Address Foreign Address (State) User 
tcp 1 0 localhost:9734 localhost:1175 TIME_WAIT root 


Remember that if you’re using a computer that has the same native and network byte ordering, you 
won't see any difference. It’s still important always to use the conversion functions to allow correct 
operation with clients and servers on computers with a different architecture. 
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Network Information 


So far, your client and server programs have had addresses and port numbers compiled into them. For 
a more general server and client program, you can use network information functions to determine 
addresses and ports to use. 


If you have permission to do so, you can add your server to the list of known services in /etc/services, 
which assigns a name to port numbers so that clients can use symbolic services rather than numbers. 


Similarly, given a computer’s name, you can determine the IP address by calling host database functions 
that resolve addresses for you. They do this by consulting network configuration files, such as /etc/hosts, 
or network information services, such as NIS (Network Information Services, formerly known as Yellow 
Pages) and DNS (Domain Name Service). 


Host database functions are declared in the interface header file net db.h. 
#include <netdb.h> 


struct hostent *gethostbyaddr(const void *addr, size_t len, int type); 
struct hostent *gethostbyname(const char *name) ; 


The structure returned by these functions must contain at least these members: 


struct hostent { 


char *h_name; /* name of the host */ 

char **h_aliases; /* list of aliases (nicknames) */ 
int h_addrtype; /* address type */ 

int h_length; /* length in bytes of the address */ 
char **h_addr_list /* list of address (network order) */ 


If there is no database entry for the specified host or address, the information functions return a 
null pointer. 


Similarly, information concerning services and associated port numbers is available through some 
service information functions. 


#include <netdb.h> 


struct servent *getservbyname(const char *name, const char *proto); 
struct servent *getservbyport(int port, const char *proto); 


The proto parameter specifies the protocol to be used to connect to the service, either "tcp" for 
SOCK_STREAM TCP connections or "udp" for SOCK_DGRAM UDP datagrams. 





The structure servent contains at least these members: 


struct servent { 


char *s_name; /* name of the service */ 

char **s aliases; /* list of aliases (alternative names) */ 

int s_port; /* The IP port number */ 

char *s_proto; /* The service type, usually "tcp" or "udp" */ 
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You can gather host database information about a computer by calling gethostbyname and printing the 
results. Note that the address list needs to be cast to the appropriate address type and converted from net- 
work ordering to a printable string using the inet_ntoa conversion, which has the following definition: 


#include <arpa/inet.h> 


char *inet_ntoa(struct in_addr in) 


The function converts an Internet host address to a string in dotted quad format. It returns -1 on error, 
but POSIX doesn’t define any specific errors. The other new function you use is gethostname. 


#include <unistd.h> 


int gethostname(char *name, int namelength) ; 


This function writes the name of the current host into the string given by name. The hostname will be 
null-terminated. The argument namelength indicates the length of the string name, and the returned 
hostname will be truncated if it’s too long to fit. gethostname returns 0 on success and -1 on error, but 
again no errors are defined in POSIX. 


Try It Out Network Information 


This program, getname .c, gets information about a host computer. 
1. As usual, make the appropriate includes and declare the variables: 


#include <netinet/in.h> 
#include <arpa/inet.h> 
#include <unistd.h> 
#include <netdb.h> 
#include <stdio.h> 
#include <stdlib.h> 


int main(int argc, char *argv[]) 
{ 
char *host, **names, **addrs; 
struct hostent *hostinfo; 


2. Set the host to the argument supplied with the getname call, or by default to the user’s machine: 


relace == 1) { 
char myname[256]; 
gethostname (myname, 255); 
host = myname; 

} 

else 
host = ara; 


3. Call gethostbyname and report an error if no information is found: 


hostinfo = gethostbyname (host) ; 
if(!thostinfo) { 
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fprintf(stderr, "cannot get info for host: %s\n", host); 
exit (1); 


4. Display the hostname and any aliases that it may have: 


printf("results for host %s:\n", host); 
printf("Name: %s\n", hostinfo -> h_name) ; 
printf ("Aliases:"); 
names = hostinfo -> h_aliases; 
while(*names) { 

printf(" %s", *names) ; 

names++; 
} 
jonealiguese (7 \ua")) 2 


5. — Warn and exit if the host in question isn’t an IP host: 
if(hostinfo -> h_addrtype != AF_INET) { 
fprintf(stderr, "not an IP host!\n"); 
exit(1); 
6. Otherwise, display the IP address(es): 
addrs = hostinfo -> h_addr_list; 


while(*addrs) { 
printf(" %s", inet_ntoa(*(struct in_addr *) *addrs) ); 


addrs++; 
} 
Pee NTE, 
exit (0); 


Alternatively, you could use the function gethostbyaddr to determine which host has a given IP address. 
You might use this in a server to find out where the client is calling from. 


How It Works 


The getname program calls gethostbyname to extract the host information from the host database. It 
prints out the hostname, its aliases (other names the computer is known by), and the IP addresses that 
the host uses on its network interfaces. On one of the authors’ systems, running the example and speci- 
fying tilde gave the two interfaces: Ethernet and modem. 


$ ./getname tilde 
results for host tilde: 
Name: tilde.localnet 
Aliases: tilde 
192.168.1.1 158.152.x.x 
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When you use the hostname, localhost, the loopback network is given. 


$ ./getname localhost 
results for host localhost: 
Name: localhost 

Aliases: 

127.0.0.1 


You can now modify your client to connect to any named host. Instead of connecting to your example 
server, you'll connect to a standard service so that you can extract the port number. 


Most UNIX and some Linux systems make their system time and date available as a standard service 
called daytime. Clients may connect to this service to discover the server’s idea of the current time and 
date. Here’s a client program, getdate .c, that does just that. 


Try It Out Connecting to a Standard Service 


1. Start with the usual includes and declarations: 


#include <sys/socket.h> 
#include <netinet/in.h> 
#include <netdb.h> 
#include <stdio.h> 
#include <unistd.h> 
#include <stdlib.h> 


int main(int argc, char *argv[]) 
{ 
char *host; 
int sockfd; 
int len, result; 
struct sockaddr_in address; 
struct hostent *hostinfo; 
struct servent *servinfo; 
char buffer[128]; 





Tearce == 1) 

host = "localhost"; 
else 

host = argv[1]; 


2. Find the host address and report an error if none is found: 
hostinfo = gethostbyname (host); 
if(!thostinfo) { 


fprintf(stderr, "no host: %s\n", host); 
Exe 
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3. Check that the daytime service exists on the host: 


servinfo = getservbyname("daytime", "tcp"); 
if(!servinfo) { 
fprintf(stderr,"no daytime service\n") ; 
Gralie (iL) 6 
} 
printf ("daytime port is %d\n", ntohs(servinfo -> s_port)); 


4. Create a socket: 
sockfd = socket (AF_INET, SOCK_STREAM, 0); 
5. Construct the address for use with connect: 
address.sin_family = AF_INET; 
address.sin_port = servinfo -> s_port; 
address.sin_addr = *(struct in_addr *)*hostinfo -> h_addr_list; 
len = sizeof (address); 


6. Then connect and get the information: 


result = connect(sockfd, (struct sockaddr *)&address, len); 


she (Geechee So Jl) f 
perror("oops: getdate"); 
exit (1); 


result = read(sockfd, buffer, sizeof(buffer) ); 
buffer[result] = '\0'; 
printf("read %d bytes: %s", result, buffer); 


close (sockfd); 
exit (0); 
You can use getdate to get the time of day from any known host. 
$ ./getdate localhost 
daytime port is 13 
read 26 bytes: 24 JUN 2007 06:03:03 BST 
$ 
If you receive an error message such as 
oops: getdate: Connection refused 
or 


oops: getdate: No such file or directory 


it may be because the computer you are connecting to has not enabled the daytime service. This has 
become the default behavior in more recent Linux systems. In the next section, you see how to enable 
this and other services. 
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How It Works 


When you run this program, you can specify a host to connect to. The daytime service port number is 
determined from the network database function getservbyname, which returns information about net- 
work services in a similar way to host information. The program getdate tries to connect to the address 
given first in the list of alternate addresses for the specified host. If successful, it reads the information 
returned by the daytime service, a character string representing the UNIX time and date. 


The Internet Daemon (xinetd/inetd) 


UNIX systems providing a number of network services often do so by way of a super-server. This pro- 
gram (the Internet daemon, xinetd or inetd) listens for connections on many port addresses at once. 
When a client connects to a service, the daemon program runs the appropriate server. This cuts down on 
the need for servers to be running all the time; they can be started as required. 


The Internet daemon is implemented in modern Linux systems by xinetd. This implementation has 
replaced the original UNIX program, inetd, although you will still see inetd in older Linux systems 
and on other UNIX-like systems. 


xinetd is usually configured through a graphical user interface for managing network services, but it is 
also possible to modify its configuration files directly. These are typically /etc/xinetd.conf and files 
in the /etc/xinetd.d directory. 


Each service that is to be provided via xinetd has a configuration file in /etc/xinetd.d. xinetd will 
read all of these configuration files when it starts up, and again if instructed to do so. 


Here are a couple of example xinetd configuration files, first for the daytime service: 


#default: off 
# description: A daytime server. This is the tcp version. 
service daytime 


{ 





socket_type = stream 
protocol = too 

wait = 710 

user = root 

type = INTERNAL 

id = daytime-stream 
FLAGS = IPv6 IPv4 


The following configuration is for the file transfer service: 


default: off 
description: 
The vsftpd FTP server serves FTP connections. It uses 
normal, unencrypted usernames and passwords for authentication. 


# 
# 
# 
# 
# vsftpd is designed to be secure. 
# 
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# NOTE: This file contains the configuration for xinetd to start vsftpd. 
# the configuration file for vsftp itself is in /etc/vsftpd.conf 
service ftp 


{ 

# server_args = 

# log_on_success += DURATION USERID 
# log_on_failure += USERID 

# nice = 10) 

socket_type = stream 

protocol = Tg 

wait = no 

user = OCI 

server = /usr/sbin/vsftpd 


The daytime service that the getdate program connects to is actually handled by xinetd itself (it 
is marked as internal) and can be made available using both SOCK_STREAM (tcp) and SOCK_DGRAM 
(udp) sockets. 


The ftp file transfer service is available only via SOCK_STREAM sockets and is provided by an external 
program, in this case vsftpd. The daemon will start these external programs when a client connects to 
the £tp port. 


To activate service configuration changes, you can edit the xinetd configuration and send a hang-up sig- 
nal to the daemon process, but we recommend that you use a more friendly way of configuring services. 
To allow your time-of-day client to connect, enable the daytime service using the tools provided on your 
Linux system. On SUSE and openSUSE the services may be configured from the SUSE Control Center as 
shown in Figure 15-1. Red Hat versions (both Enterprise Linux and Fedora) have a similar configuration 
interface. Here, the daytime service is being enabled for both TCP and UDP queries. 


For systems that use inetd rather than xinetd, here’s the equivalent extract from the inetd configura- 
tion file, /etc/inetd. conf, which is used by inetd to decide which servers to run: 


# 

# <service_name> <sock_type> <proto> <flags> <user> <server_path> <args> 

# 

# Echo, discard, daytime, and chargen are used primarily for testing. 

# 

daytime stream EGJ nowait root internal 

daytime dgram udp wait root internal 

# 

# These are standard services. 

# 

ftp stream tcp nowait root /usr/sbin/tcpd /usr/sbin/wu.ftpd 
telnet stream tcp nowait root /usr/sbin/tcpd /usr/sbin/in.telnetd 
# 


# End of inetd.conf. 
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Note that in this example the ftp service is provided by the external program wu. ftpd. If your system is 
running inetd, you can change the services provided by editing /etc/inetd.conf (a # at the start of a 
line indicates that the line is a comment) and restarting the inetd process. This can be done by sending 
it a hang-up signal using ki11. To make this easier, some systems are configured so that inetd writes its 
process ID to a file. Alternatively, killal1 can be used: 


# killall -HUP inetd 


Socket Options 


There are many options that you can use to control the behavior of socket connections — too many to 
detail here. The setsockopt function is used to manipulate options. 


#include <sys/socket.h> 


int setsockopt(int socket, int level, int option_name, 
const void *option_value, size_t option_len); 
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You can set options at various levels in the protocol hierarchy. To set options at the socket level, you 
must set level to SOL_SOCKET. To set options at the underlying protocol level (TCP, UDP, and so on), 
set level to the number of the protocol (from either the header file netinet/in.h or as obtained by the 
function getprotobyname). 





The option_name parameter selects an option to set; the option_value parameter is an arbitrary value 
of length option_len bytes passed unchanged to the underlying protocol handler. 


Socket level options defined in sys/socket .h include the following. 


OPTION DESCRIPTION 

SO_DEBUG Turn on debugging information. 

SO_KEEPALIVE Keep connections active with periodic transmissions. 
SO_LINGER Complete transmission before close. 


SO_DEBUG and SO_KEEPALIVE take an integer option_value used to turn the option on (1) or off (0). 
SO_LINGER requires a linger structure defined in sys/socket .h to define the state of the option and the 
linger interval. 


setsockopt returns 0 if successful, -1 otherwise. The manual pages describe further options and errors. 


Multiple Clients 


So far in this chapter, you’ve seen how you can use sockets to implement client/server systems both 
locally and across networks. Once established, socket connections behave like low-level open file 
descriptors and in many ways like bi-directional pipes. 


You might need to consider the case of multiple, simultaneous clients connecting to a server. You’ve seen 
that when a server program accepts a new connection from a client, a new socket is created and the original 
listen socket remains available for further connections. If the server doesn’t immediately accept further con- 
nections, they will be held pending in a queue. 


The fact that the original socket is still available and that sockets behave as file descriptors gives you a 
method of serving multiple clients at the same time. If the server calls fork to create a second copy of 
itself, the open socket will be inherited by the new child process. It can then communicate with the con- 
necting client while the main server continues to accept further client connections. This is, in fact, a fairly 
easy change to make to your server program, which is shown in the following Try It Out section. 


Because you're creating child processes but not waiting for them to complete, you must arrange for the 
server to ignore SIGCHLD signals to prevent zombie processes. 


Try It Out A Server for Multiple Clients 


1. This program, server4 .c, begins in a similar vein to the last server, with the notable addition 
of an include for the signal .h header file. The variables and the procedure of creating and 
naming a socket are the same: 
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#include <sys/types.h> 
#include <sys/socket.h> 
#include <stdio.h> 
#include <netinet/in.h> 
#include <signal.h> 
#include <unistd.h> 
#include <stdlib.h> 


int main() 

{ 
int server_sockfd, client_sockfd; 
int server_len, client_len; 
struct sockaddr_in server_address; 
struct sockaddr_in client_address; 


server_sockfd = socket (AF_INET, SOCK_STREAM, 0); 





server_address.sin_family = AF_INET; 

server_address.sin_addr.s_addr = htonl(INADDR_ANY) ; 
server_address.sin_port = htons (9734); 

server_len = sizeof (server_address) ; 

bind(server_sockfd, (struct sockaddr *)&server_address, server_len); 


Create a connection queue, ignore child exit details, and wait for clients: 
listen(server_sockfd, 5); 
signal (SIGCHLD, SIG_IGN) ; 


while(1) { 
char eh; 


printf ("server waiting\n"); 
Accept the connection: 


client_len = sizeof (client_address) ; 
client_sockfd = accept (server_sockfd, 
(struct sockaddr *)&client_address, &client_len) ; 


Fork to create a process for this client and perform a test to see whether you're the parent or 
the child: 


if(fork() == 0) { 


If you're the child, you can now read/write to the client on client_sockfd. The five-second 
delay is just for this demonstration: 


read(client_sockfd, &ch, 1); 
sleep (5); 

ch++; 

write(client_sockfd, &ch, 1); 
close(client_sockfd) ; 

exit (0); 
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6. Otherwise, you must be the parent and your work for this client is finished: 


else { 
close(client_sockfd) ; 
} 


The code inserts a five-second delay in the processing of the client’s request to simulate server calcula- 
tion or database access. If you had done this with the previous server, each run of client3 would have 
taken five seconds. With the new server, you can handle multiple client3 programs concurrently, with 
an overall elapsed time of just over five seconds. 


$ ./server4 & 

[1] 26566 

server waiting 

$ ./client3 & ./client3 & ./client3 & ps x 


[2] 26581 
[3] 26582 
[4] 26583 


server waiting 
server waiting 
server waiting 
PID TTY STAT TIME COMMAND 








26566 pts/1 S 0:00 ./server4 
26581 pts/1 S 0:00 ./client3 
26582 pts/1 S 0:00 ./client3 
26583 pts/1 S 0:00 ./client3 
26584 pts/1 R+ 0:00 ps x 
26585 pts/1 S 0:00 ./server4 
26586 pts/1 S 0:00 ./server4 
26587 pts/1 S 0:00 ./server4 
$ char from server = B 
char from server = B 
char from server = B 
ps X 
PID TTY STAT TIME COMMAND 

26566 pts/1 S 0:00 ./server4 
26590 pts/1 R+ 0:00 ps x 
[2] Done ./client3 
[3]- Done ./client3 
[4]+ Done ./client3 
$ 

How It Works 


The server program now creates a new child process to handle each client, so you see several server 
waiting messages as the main program continues to wait for new connections. The ps output (edited 
here) shows the main server4 process, PID 26566, waiting for new clients while the three client3 
processes are being served by three children of the server. After a five-second pause, all of the clients 
get their results and finish. The child server processes exit to leave just the main server alone again. 
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The server program uses fork to handle multiple clients. In a database application, this may not be the 
best solution, because the server program may be quite large and there is still the problem of coordinat- 
ing database accesses from multiple server copies. In fact, what you really need is a way for a single 
server to handle multiple clients without blocking and waiting on client requests to arrive. The solution 
to this problem involves handling multiple open file descriptors at once and isn’t limited to socket appli- 
cations. Enter select. 





select 


Quite often when you're writing Linux applications, you may need to examine the state of a number of 
inputs to determine the next action to take. For example, a communication program such as a terminal 
emulator needs to read the keyboard and the serial port effectively at the same time. In a single-user sys- 
tem, it might be acceptable to run in a “busy wait” loop, repeatedly scanning the input for data and 
reading it if it arrives. This behavior is expensive in terms of CPU time. 


The select system call allows a program to wait for input to arrive (or output to complete) on a num- 
ber of low-level file descriptors at once. This means that the terminal emulator program can block until 
there is something to do. Similarly, a server can deal with multiple clients by waiting for a request on 
many open sockets at the same time. 


The select function operates on data structures, fd_set, that are sets of open file descriptors. A number 
of macros are defined for manipulating these sets: 


#include <sys/types.h> 
#include <sys/time.h> 


void FD_ZERO(fd_set *fdset) ; 

void FD_CLR(int fd, fd_set *fdset); 
void FD_SET(int fd, fd_set *fdset); 
int FD ISSET(int fd, fd_set *fdset); 





As suggested by their names, FD_ZERO initializes an £d_set to the empty set, FD_SET and FD_CLR set 
and clear elements of the set corresponding to the file descriptor passed as fd, and FD_ISSET returns 
nonzero if the file descriptor referred to by fd is an element of the £d_set pointed to by £dset. The 
maximum number of file descriptors in an £d_set structure is given by the constant FD_SETSIZE. 


The select function can also use a timeout value to prevent indefinite blocking. The timeout value is 
given using a struct timeval. This structure, defined in sys/time.h, has the following members: 


struct timeval { 
time_t tv_sec; /* seconds */ 
long tv_usec; /* microseconds */ 


} 


The time_t type is defined in sys/types .h as an integral type. 
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The select system call has the following prototype: 


#include <sys/types.h> 
#include <sys/time.h> 


int select(int nfds, fd_set *readfds, fd_set *writefds, 
fd_set *errorfds, struct timeval *timeout) ; 


A call to select is used to test whether any one of a set of file descriptors is ready for reading or writing 
or has an error condition pending and will optionally block until one is ready. 


The nfds argument specifies the number of file descriptors to be tested, and descriptors from 0 to nfds-1 
are considered. Each of the three descriptor sets may be a null pointer, in which case the associated test 
isn’t carried out. 


The select function will return if any of the descriptors in the readfds set are ready for reading, if any 
in the writefds set are ready for writing, or if any in errorfds have an error condition. If none of these 
conditions apply, select will return after an interval specified by timeout. If the timeout parameter is 
a null pointer and there is no activity on the sockets, the call will block forever. 


When select returns, the descriptor sets will have been modified to indicate which descriptors are 
ready for reading or writing or have errors. You should use FD_ISSET to test them, to determine the 
descriptor(s) needing attention. You can modify the timeout value to indicate the time remaining until 
the next timeout, but this behavior isn’t specified by X/Open. In the case of a timeout occurring, all 
descriptor sets will be empty. 


The select call returns the total number of descriptors in the modified sets. It returns —1 on failure, 
setting errno to describe the error. Possible errors are EBADF for invalid descriptors, EINTR for return 
due to interrupt, and EINVAL for bad values for nfds or timeout. 


Although Linux modifies the structure pointed to by timeout to indicate the time remaining, most 
versions of UNIX do not. Much existing code that uses the select function initializes a timeval 
structure and then continues to use it without ever reinitializing the contents. On Linux, this code may 
operate incorrectly because Linux is modifying the timeval structure every time a timeout occurs. If 
you're writing or porting code that uses the select function, you should watch out for this difference 
and always reinitialize the timeout. Note that both behaviors are correct; they're just different! 


Try It Out select 


Here is a program, select .c, to illustrate the use of select. You'll see a more complete example a little 
later. This program reads the keyboard (standard input — file descriptor 0) with a timeout of 2.5 seconds. 
It reads the keyboard only when input is ready. It’s quite straightforward to extend it to include other 
descriptors, such as serial lines or pipes and sockets, depending on the application. 


1. Begin as usual with the includes and declarations and then initialize inputs to handle input 
from the keyboard: 


#include <sys/types.h> 
#include <sys/time.h> 
#include <stdio.h> 
#include <fcntl.h> 
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#include <sys/ioctl.h> 
#include <unistd.h> 
#include <stdlib.h> 


int main() 

{ 
char buffer[128]; 
int result, nread; 


fd_set inputs, testfds; 
struct timeval timeout; 


FD_ZERO(&inputs) ; 
FD_SET(0,&inputs) ; 


2. Wait for input on stdin for a maximum of 2.5 seconds: 


while(1) { 
testfds = inputs; 
timeout.tv_sec = 2; 
timeout.tv_usec = 500000; 


result = select(FD_SETSIZE, &testfds, (fd_set *)NULL, (fd_set *)NULL, 
&timeout) ; 


3. After this time, test result. If there has been no input, the program loops again. If there has 
been an error, the program exits: 


switch(result) { 


case 0: 
printf ("timeout\n"); 
break; 

case -1: 
perror("select"); 
exit (1); 


4. If, during the wait, you have some action on the file descriptor, read the input on stdin and 
echo it whenever an <end of line> character is received, until that input is Ctrl+D: 


default: 
if (FD_ISSET(0,&testfds)) { 
ioct1(0,FIONREAD, &nread) ; 








if(nread == 0) { 
printf ("keyboard done\n") ; 
exit (0); 

} 


nread = read(0,buffer,nread) ; 
buffer[nread] = 0; 

printf("read %d from keyboard: %s", nread, buffer); 
} 

break; 
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When you run this program, it prints timeout every two and a half seconds. If you type at the key- 
board, it reads the standard input and reports what was typed. With most shells, the input will be sent to 
the program when the user presses the Enter (or Return) key or keys in a control sequence, so your pro- 
gram will print the input whenever you press Enter. Note that the Enter key itself is read and processed 
like any other character (try this by not pressing Enter, but a number of characters followed by Ctrl+D). 


$ ./select 

timeout 

hello 

read 6 from keyboard: hello 
fred 

read 5 from keyboard: fred 
timeout 

4D 

keyboard done 

$ 


How It Works 


The program uses the select call to examine the state of the standard input. By arranging a timeout 
value, the program resumes every 2.5 seconds to print a timeout message. This is indicated by select 
returning zero. On end of file, the standard input descriptor is flagged as ready for input, but there are 
no characters to be read. 


Multiple Clients 


Your simple server program can benefit by using select to handle multiple clients simultaneously, 
without resorting to child processes. For real applications using this technique, you must take care that 
you do not make other clients wait too long while you deal with the first to connect. 


The server can use select on both the listen socket and the clients’ connection sockets at the same time. 
Once activity has been indicated, you can use FD_ISSET to cycle through all the possible file descriptors 
to discover which one the activity is on. 


If the listen socket is ready for input, this will mean that a client is attempting to connect and you can 
call accept without risk of blocking. If a client descriptor is indicated ready, this means that there’s a 
client request pending that you can read and deal with. A read of zero bytes will indicate that a client 
process has ended and you can close the socket and remove it from your descriptor set. 


Try It Out An Improved Multiple Client/Server 


{. For the final example, server5 .c, you'll include the sys/time.h and sys/ioct1.h headers 
instead of signal .h as in the last program, and declare some extra variables to deal with 
select: 


#include <sys/types.h> 


#include <sys/socket .h> 
#include <stdio.h> 
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#include <netinet/in.h> 
#include <sys/time.h> 
#include <sys/ioctl.h> 
#include <unistd.h> 
#include <stdlib.h> 


int main() 

{ 
int server_sockfd, client_sockfd; 
int server_len, client_len; 
struct sockaddr_in server_address; 
struct sockaddr_in client_address; 
int result; 
fd_set readfds, testfds; 


Create and name a socket for the server: 


server_sockfd = socket (AF_INET, SOCK_STREAM, 0); 





server_address.sin_family = AF_INET; 
server_address.sin_addr.s_addr = htonl(INADDR_ANY) ; 
server_address.sin_port = htons (9734); 

server_len = sizeof (server_address) ; 


bind(server_sockfd, (struct sockaddr *)&server_address, server_len); 


Create a connection queue and initialize readfds to handle input from server_sockfd: 
listen(server_sockfd, 5); 
FD_ZERO (&readfds) ; 
FD_SET(server_sockfd, &readfds) ; 
Now wait for clients and requests. Because you have passed a null pointer as the timeout 
parameter, no timeout will occur. The program will exit and report an error if select returns a 
value less than 1: 
while(1) { 
char ch: 
int fd; 


int nread; 
testfds = readfds; 


printf ("server waiting\n"); 
result = select(FD_SETSIZE, &testfds, (fd_set *)0, 
(fd-set *)0, struct timeval *) 0). 


if(result < 1) { 
perror("server5"); 
exit (1); 
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5. Once you know you've got activity, you can find which descriptor it’s on by checking each in 
turn using FD_ISSET: 





igo (Geel = 0)? iecl << iin) (SisuMsivAne vecHtss)) if 
if (FD_ISSET(fd,&testfds)) { 


6. If the activity is on server_sockfd, it must be a request for a new connection, and you add the 
associated client_sockfd to the descriptor set: 


if(fd == server_sockfd) { 
client_len = sizeof(client_address) ; 
client_sockfd = accept (server_sockfd, 
(struct sockaddr *)&client_address, &client_len) ; 
FD_SET(client_sockfd, &readfds) ; 
printf ("adding client on fd %d\n", client_sockfd) ; 


7. — Ifitisn’t the server, it must be client activity. If close is received, the client has gone away, and 
you remove it from the descriptor set. Otherwise, you “serve” the client as in the previous 
examples. 


else { 
ioctl(fd, FIONREAD, &nread) ; 





if(nread == 0) { 

close (fd); 

FD_CLR(fd, &readfds) ; 

printf ("removing client on fd %d\n", fd); 
} 


else { 
read(fd, &ch, 1); 
sleep (5); 
printf("serving client on fd %d\n", fd); 
Elig 


write(fd, &ch, 1); 


In a real-world program, it would be advisable to include a variable holding the largest £A number con- 
nected (not necessarily the most recent £A number connected). This would prevent looping through 
potentially thousands of £ds that aren't even connected and couldn't possibly be ready for reading. 
We've omitted it here simply for brevity’s sake and to make the code simpler. 
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When you run this version of the server, it deals with multiple clients sequentially in a single process. 


$ ./server5 & 

1] 26686 

server waiting 

$ ./client3 & ./client3 & ./client3 & ps x 
2] 26689 

3] 26690 

adding client on fd 4 

server waiting 

4] 26691 

PID TTY STAT TIME COMMAND 
26686 pts/1 S :00 ./server5 
26689 pts/1 S :00 ./client3 
26690 pts/1 S :00 ./client3 
26691 pts/1 S :00 ./client3 
26692 pts/1 R+ :00 ps x 

$ serving client on fd 4 

server waiting 

adding client on fd 5 

server waiting 

adding client on fd 6 

char from server = B 

serving client on fd 5 

server waiting 

removing client on fd 4 

char from server = B 

serving client on fd 6 

server waiting 

removing client on fd 5 

server waiting 

char from server = B 

removing client on fd 6 

server waiting 











E ka C E 


[2] Done ./client3 
[3]- Done ./client3 
[4]+ Done ./client3 
$ 


To complete the analogy at the start of the chapter, the following table shows the parallels between 
socket connections and a telephone exchange. 


Telephone Network Sockets 

Call company on 555-0828 Connect to IP address 127.0.0.1. 

Call answered by reception Connection established to remote host. 
Ask for finance department Route using specified port (9734). 


Continued on next page 
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Telephone Network Sockets 
Call answered by finance administration Server returns from select. 
Call put through to free account manager Server calls accept, creating new socket on 


extension 456. 


Datagrams 


In this chapter, we have concentrated on programming applications that maintain connections to their 
clients, using connection-oriented TCP socket connections. There are cases where the overhead of estab- 
lishing and maintaining a socket connection is unnecessary. 


The daytime service used in getdate.c earlier provides a good example. You create a socket, make a 
connection, read a single response, and close the connection. That’s a lot of operations just to get the date. 


The daytime service is also available by UDP using datagrams. To use it, you send a single datagram to 
the service and get a single datagram containing the date and time in response. It’s simple. 


Services provided by UDP are typically used where a client needs to make a short query of a server and 
expects a single short response. If the cost in terms of processing time is low enough, the server is able to 
provide this service by dealing with requests from clients one at a time, allowing the operating system 
to hold incoming requests in a queue. This simplifies the coding of the server. 


Because UDP is not a guaranteed service, however, you may find that your datagram or your response goes 
missing. So if the data is important to you, you would need to code your UDP clients carefully to check for 
errors and retry if necessary. In practice, on a local area network, UDP datagrams are very reliable. 


To access a service provided by UDP, you need to use the socket and close system calls as before, but 
rather than using read and write on the socket, you use two datagram-specific system calls, sendto 
and recvfrom. 


Here’s a modified version of getdate .c that gets the date via a UDP datagram service. Changes from 
the earlier version are highlighted. 


/* Start with the usual includes and declarations. */ 


#include <sys/socket .h> 
#include <netinet/in.h> 
#include <netdb.h> 
#include <stdio.h> 
#include <unistd.h> 
#include <stdlib.h> 


int main(int argc, char *argv[]) 





char *host; 
int sockfd; 
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int len, result; 

struct sockaddr_in address; 
struct hostent *hostinfo; 
struct servent *servinfo; 
char buffer[128]; 


if(arge == 1) 

host = "localhost"; 
else 

host = argv[1]; 


Find the host address and report an error if none is found. */ 


hostinfo = gethostbyname (host); 
if(thostinfo) { 
fprintf(stderr, "no host: %s\n", host); 
exit(1); 


Check that the daytime service exists on the host. */ 


servinfo = getservbyname("daytime", "udp"); 
if(!servinfo) { 
fprintf(stderr,"no daytime service\n"); 
exit(1); 
} 
printf ("daytime port is %d\n", ntohs(servinfo -> s_port)); 


Create a UDP socket. */ 


sockfd = socket (AF_INET, SOCK_DGRAM, 0); 





Construct the address for use with sendto/recvfrom... */ 


address.sin_family = AF_INET; 

address.sin_port = servinfo -> s_port; 

address.sin_addr = *(struct in_addr *)*hostinfo -> h_addr_list; 
len = sizeof (address); 


result sendto(sockfd, buffer, 1, 0, (struct sockaddr *)&address, len); 
result = recvfrom(sockfd, buffer, sizeof(buffer), 0, 
(struct sockaddr *)&address, &len) ; 
buffer[result] = '\0'; 
printf("read %d bytes: %s", result, buffer); 


close(sockfd) ; 
exit (0); 


As you can see, the changes required are very small. You find the daytime service with getservbyname 
as before, but you specify the datagram service by requesting the UDP protocol. You create a datagram 
socket using socket with a SOCK_DGRAM parameter. You set up the destination address as before, but now 
you have to send a datagram rather than just read from the socket. 
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Because you are not making an explicit connection to services provided by UDP, you have to have some 
way of letting the server know that you want to receive a response. In this case, you send a datagram 
(here you send a single byte from the buffer you are going to receive the response into) to the service, 
and it responds with the date and time. 


The sendto system call sends a datagram from a buffer on a socket using a socket address and address 
length. Its prototype is essentially 


int sendto(int sockfd, void *buffer, size_t len, int flags, 
struct sockaddr *to, socklen_t tolen); 


In normal use, the flags parameter can be kept zero. 


The recvfrom system call waits on a socket for a datagram from a specified address and receives it into 
a buffer. Its prototype is essentially 


int recvfrom(int sockfd, void *buffer, size_t len, int flags, 
struct sockaddr *from, socklen_t *fromlen) ; 


Again, in normal use, the flags parameter can be kept zero. 


To keep the example short, we have omitted error handling. Both sendto and recvfrom will return | 1 if 
an error occurs and will set errno appropriately. Possible errors include the following: 


To keep the example short we have omitted error 


Errno Value Description 
EBADF An invalid file descriptor was passed. 
EINTR A signal occurred. 


Unless the socket is set nonblocking using fcnt1 (as you saw for accepting TCP connections earlier), the 
recvfrom call will block indefinitely. The socket can, however, be used with select and a timeout to deter- 
mine whether any data has arrived in the same way that you have seen with the connection-based servers 
earlier. Alternatively, an alarm clock signal can be used to interrupt a receive operation (see Chapter 11). 


Summary 


In this chapter, we’ve covered another method of inter-process communication: sockets. These allow you 
to develop true distributed client/server applications to run across networks. We briefly covered some 
of the host database information functions and how Linux handles standard system services with the 
Internet daemon. You worked through a number of client/server example programs that demonstrate 
networking and handling multiple clients. 


Finally, you learned about the select system call that allows a program to be advised of input and 
output activity on several open file descriptors and sockets at once. 
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Programming 
GNOME Using GTK+ 





So far in this book, we’ve covered the major topics in Linux programming that deal with complex, 
under-the-hood stuff. Now it’s time to breathe some life into your applications and look at how to 
add a Graphical User Interface (GUI) to them. In this chapter and Chapter 17, we’re going to look 
at the two most popular GUI libraries for Linux: GTK+ and KDE/(Qt. These libraries correspond to 
the two most popular Linux desktop environments: GNOME (GTK+) and KDE. 


All GUI libraries in Linux sit on top of the underlying windowing system called the X Window 
System (or more commonly X11 or just X), so before we delve into GNOME/GTK+ details we pro- 
vide an overview of how X operates and help you understand how the various layers of the win- 
dowing system fit together to create what we call the desktop. 


In this chapter, we cover 


The X Window System 

An introduction to GNOME/GTK+ 
GTK+ widgets 

GNOME widgets and menus 

Dialogs 

CD Database GUI using GNOME/GTK+ 





COococovo o 


Introducing X 


If you’ve ever used a desktop windowing system on Linux, then you’ve most likely used X, an open 
source graphics system. One of the most innovative, and ultimately frustrating, features of X is the 
rigid adherence to the mantra of mechanism, not policy. That means X defines no user interface, but 
provides the means to make one. This means you're free to create your own entire desktop environ- 
ment, experimenting and innovating at will. But, it also hindered user interfaces on Linux and 
UNIX for a long time. Into this relative void, two desktop projects emerged as the favorites of Linux 
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users: GNOME and KDE. The Linux desktop does not begin and end with X, however. In truth, the desk- 
top in Linux is a rather nebulous thing, with no single project or group releasing a definitive version. A 
modern installation contains a myriad of libraries, utilities, and applications that collectively are called 
“the desktop.” 


X has a long and illustrious history, having been originally developed at MIT in the early 1980s. X was 
developed to provide a unified windowing system for the high-end scientific workstations of the day, 
which were hugely expensive, number-crunching beasts. 


As the 1990s came and hardware prices dropped, X was ported by enthusiasts to run on inexpensive 
home PCs, a project that became known as XFree86 (PC processors made by Intel and other companies 
are known as x86 processors), and it is the descendants of XFree86 that are distributed today with Linux, 
with most Linux distributions using an X variant called X.Org. 


The X Window System is separated into hardware-level and application-level components known as 
the X server and the X client. These components communicate using the aptly named X Protocol. The 
following sections look at each of these in turn. 


X Server 


The X server runs on the user’s local machine and is the part that performs the low-level operation of 
drawing the graphics onscreen. The server part of the name often confuses: the X server runs on your 
desktop PC. X clients may run on your desktop PC, or X clients can actually run on other systems on 
your network — including servers. The reversed terminology actually makes sense when you think 
about it, but it often seems backwards. 


Because the X server talks directly to the graphics card, you must use an X server specific to your graphics 
card, and it must be configured with appropriate resolution, refresh rate, color depth, and so on. The con- 
figuration file is named xorg.conf or X£Eree86Config. In the past, you usually had to manually edit the 
configuration file to get X working properly. Thankfully, modern Linux distributions autodetect the cor- 
rect settings, saving users time and a great deal of head scratching! 


The X server listens for user input via the mouse and keyboard and relays keyboard presses and mouse 
clicks to X client applications. These messages are called events; they form a key element of GUI pro- 
gramming. We look at events and their logical GTK+ extension, signals, in detail later in this chapter. 


X Client 


An X client is any program that uses the X Window System as a GUI. Examples are xterm, xcalc, 
and more advanced applications, like Abiword. An X client typically waits for user events sent by 
the X server and responds by sending redraw messages back to the server. 


The X client need not be on the same machine as the X server. 


X Protocol 


The X client and X server communicate using the X Protocol, which enables the client and server to be 
separated over a network. For instance, you can run an X client application from a remote computer on 
the Internet or over an encrypted Virtual Private Network (VPN). For the vast majority of personal 
Linux systems, X clients and the X server run on the same system. 
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Xlib 


Xlib is the library used indirectly by an X client to generate the X Protocol messages. It provides a very low- 
level API to allow the client to draw very basic elements on the X server and to respond to the simplest of 
inputs. We must emphasize that Xlib is very low level — to create something even as simple as a menu 
using Xlib is an incredibly laborious process that needs hundreds of lines of code. 


A GUI programmer cannot sensibly program directly with Xlib. You need an API that makes GUI 
elements such as menus, buttons, and drop-down lists easy and simple to create. In a nutshell, this 
is the role of the toolkit. 


Toolkits 


A toolkit is a GUI library that X clients utilize to greatly simplify the creation of windows, menus, but- 
tons, and so on. Using a toolkit, you can create buttons, menus, frames, and the like with single func- 
tion calls. The generic term for GUI elements such as these is widgets, a universal term you'll find in all 
modern GUI libraries. 


There are dozens of toolkits for X to choose from, each with their defining strengths and weaknesses. 
Which one you choose is an important design decision for your application, and some of the factors you 
should consider are 

Q Who are you targeting with your application? 
Will your users have the toolkit libraries installed? 
Does the toolkit have a port for other popular operating systems? 
What software license does the toolkit use, and is it compatible with your intended use? 


Does the toolkit support your programming language? 


Oooo so 


Does the toolkit have a modern look and feel? 


Historically, the most popular toolkits were Motif, OpenLook, and Xt, but these have been largely 
superceded by the technically superior GTK+ and Qt toolkits that form the basis of the GNOME and 
KDE desktops, respectively. 


Window Managers 


The final piece in the X puzzle is the window manager, which is responsible for positioning windows 
onscreen. Window managers often support separate “workspaces” that divide the desktop, increasing the 
area with which you can interact. The window manager is also responsible for adding decoration around 
each window, which usually consists of a frame and title bar with maximize, minimize, and close icons. 
Window managers provide part of the look and feel of the desktop, such as the window title bars. 


Common window managers include: 


Q Metacity, the default window manager for the GNOME desktop. 
Qo KWin, the default window manager for the KDE desktop. 
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m) 
Q) 





Openbox, designed to conserve resources and run on older, slower systems. 


Enlightenment, a window manager that displays awesome graphics and effects. 


As with everything in X, you can switch window managers. Most users, though, run the window man- 
ager that comes with their desktop environment. 


Other Ways to Create a GUI — Platform-Independent 
Windowing APIs 


It’s worth mentioning other ways to create GUIs that are not specific to Linux — there are languages that 
have native GUI support that function under Linux: 


Q 





The Java Language supports programming GUIs using the Swing and older AWT APIs. The 
look and feel of Java GUIs isn’t to everybody’s taste, and on older machines the interface can 
feel clunky and unresponsive. A great advantage of Java is that once you’ve compiled your Java 
code, it runs unchanged on any platform with a Java Virtual Machine, which includes Linux, 
Windows, Mac OS, and mobile devices. See http: //java.sun.com for more information. 


C# is a programming language very similar to Java. On Linux, the C# Common Language 
Runtime, or CLR, platform comes from the Mono project at http: //www.mono-project.com. 
C# on the Mono platform supports both Windows. Forms, also used on Windows, and a special 
binding to the GTK+ toolkit, called Gtk#. 


Tel/Tk is a scripting language that is excellent for rapid development of GUIs and works with X, 
Windows, and Mac OS. It’s great for rapid prototyping or for small utilities where you want the 
simplicity and maintainability of a script. You can find all the details at http: //tcl.tk. 


Python is also a scripting language. You can use the Tk part of Tcl/Tk from Python, or you can 
program to the Python GTK+ binding, writing GTK+ programs in Python. You can find more 
about Python at http: //www.python. org. 


Perl is another common Linux scripting language. You can use the Tk part of Tcl/Tk from Perl, 
as Perl/Tk. You can find more about Perl at http: //www.perl.org/. 


With the platform independence that these languages bring there is a price to pay. Sharing informa- 
tion with native applications — for instance, using “drag and drop” — is difficult, and saving config- 
uration usually has to be done in a proprietary rather than the desktop standard way. Sometimes 
vendors of Java software cheat by shipping with platform-specific extensions to get around these 
sorts of problems. 


Introducing GTK+ 


Now that you’ve looked at the X Window System, it’s time to look at the GTK+ Toolkit. GTK+ started 
out life as part of the popular GNU Image Manipulation Program, The GIMP, which is how GTK derives 
its name (The Gimp ToolKit). The GIMP programmers clearly had great foresight in making GTK+ a 
project in its own right because it has grown and developed into one of the most powerful and popular 
toolkits around. The homepage of the GTK+ project is http: //www.gtk.org. 
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To recap, GTK+ is a library that greatly simplifies the creation of Graphical User Interfaces (GUIs) by 
providing a set of ready-made components called widgets that you bolt together with easy-to-use func- 
tion calls to your application logic. 


Although GTK+ is a GNU project like The GIMP, it is released under the terms of the more liberal LGPL 
(Lesser General Public License) that permits software (including closed source proprietary software) to 
be written using GTK+ without payment of fees, royalties, or other restrictions. The freedom offered by 
the GTK+ license is in contrast to its competitor Qt (the subject of the next chapter), whose GPL license 
prohibits commercial software from being developed using Ot (you must instead purchase a commercial 
Qt license in that case). 


GTK+ is written entirely in C, and the majority of GTK+ software is also written in C. Fortunately there 
are a number of language bindings that allow you to use GTK+ in your preferred language, be it C++, 
Python, PHP, Ruby, Perl, C#, or Java. 


GTK+ itself is built on top of a number of other libraries. These include: 


Q GLib — provides low-level data structures, types, thread support, the event loop, and 
dynamic loading. 


Q GObject — implements an object-oriented system in C without requiring C++. 


D 


Pango — supports text rendering and layout. 


Q ATK — helps you create accessible applications and allows users to run your applications with 
screen readers and other accessibility tools. 


ū GDK, the GIMP Drawing Kit — handles low-level graphics rendering on top of the Xlib. 
Q GdkPixbuf — helps manipulate images within GTK+ programs. 
Q Xlib — provides the low-level graphics on Linux and UNIX systems. 


GLib Type System 


If you’ve ever browsed through GTK+ code, you may have wondered why you saw a lot of C data types 
prefixed with the letter g, such as gint, gchar, gshort, as well as unfamiliar types such as gint32 and 
gpointer. This is because GTK+ is based on C portability libraries called GLib and GObject that define 
these types to aid in cross-platform development. 


GLib and GObject aid cross-platform development by providing a standard set of replacement data 
types, functions, and macros to handle memory management and common tasks. These types, functions, 
and macros mean that as GTK+ programmers we can be confident that our code will port reliably to 
other platforms and architectures. 


GLib also defines some convenient constants: 
#include <glib/gmacros.h> 


#define FALSE 0 
#define TRUE !FALSE 
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The additional data types are essentially those that are replacements for the standard C types (for consis- 
tency and readability) and those that guarantee byte length across all platforms: 


Q gint, guint, gchar, guchar, glong, gulong, gfloat, and gdouble are simple replacements 
for the standard C types for consistency. 


Q = gpointer is synonymous with (void *). 


(m 


gboolean is useful for representing boolean values and is a wrapper for int. 





Q gint8, guint8, gint16, guint16, gint32, and guint32 are signed and unsigned types with a 
guaranteed byte length. 


Usefully, using GLib and GObject is almost transparent. GLib is used extensively in GTK+, so if you 
have a working GTK+ setup, you'll find GLib installed. When programming with GTK+ you don’t even 
need to explicitly include the glib.h header file, as you'll see later in the chapter. 


GTK+ Object System 


Anybody who has experimented with GUI programming before will probably understand when we 
write that GUI libraries strongly lend themselves to the paradigm of object-oriented (OO) programming; 
so much so that all modern toolkits are written in an object-oriented fashion, including GTK+. 


Despite GTK+ being written purely in C, it supports objects and OO programming through the Gobject 
library. This library supports object inheritance and polymorphism using macros. 


Let’s look at an example of inheritance and polymorphism by looking at the Gtkwindow object hierarchy 
taken from the GTK+ API documentation: 


GObject 
+----GInitiallyUnowned 
+----GtkObject 
+----GtkWidget 
+----GtkContainer 
+----GtkBin 
+----GtkWindow 


This list of objects tells you that Gtkwindow is a child of GtkBin, and therefore any function you can call 
with a GtkBin can be called with GtkwWindow. Similarly, Gtkwindow inherits from GtkContainer, which 
inherits from GtkWidget. 

As a matter of convenience, all widget creation functions return a GtkWidget type. For example: 


GtkWidget* gtk_window_new (GtkWindowType type); 


Suppose you create a GtkWindow, and want to pass the returned value to a function that expects a 
GtkContainer such as gtk_container_add: 


void gtk_container_add (GtkContainer *container, GtkWidget *widget) ; 
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You use the GTK_CONTAINER macro to cast between a GtkWidget and GtkContainer: 








GtkWidget * window = gtk_window_new(GTK GTK_WINDOW_TOPLEVEL) ; 
gtk_container_add(GTK_CONTAINER (window), awidget) ; 





You'll see the meaning of these functions later; for now, notice that macros are frequently used. Macros 
exist for every conceivable cast. 


Don’t worry if all this is a little unclear; you don’t need to understand OO programming in any detail 
to come to grips with GNOME/GTK-+-. In fact, it’s a painless way to learn the ideas and benefits behind 
OO programming while still in the comfort zone of C. 


Introducing GNOME 


GNOME is the name given to a project started in 1997 by programmers working on the GNU Image 
Manipulation Program (The GIMP) to create a unified desktop for Linux. There was a general consensus 
that adoption of Linux as a desktop platform was being held back by the lack of a coherent strategy. At that 
time, the Linux desktop resembled the Wild West, with no overall standards or agreed-upon practices and 
an “anything goes” programmer mentality. With no overarching group controlling things such as desktop 
menus, a consistent look and feel, documentation, translation, and so on, the newbie experience on the 
desktop was at best confusing and at worst unusable. 


The GNOME team set out to create a desktop for Linux licensed entirely under the GPL, developing 
utilities and configuration programs in a uniform and consistent style while promoting standards for 
inter-application communication, printing, session-management, and best-practices in GUI application 
programming. 


The results of their efforts are clear for all to see — GNOME is the basis of the default Linux desktop for 
the Fedora, Red Hat, Ubuntu, and openSUSE distributions, among others (see Figure 16-1). 
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GNOME originally stood for the GNU Network Object Model Environment — this reflects one of the 
early goals, which was to introduce an object framework to Linux like the Microsoft OLE, so that you 
could embed, for example, a spreadsheet in a word processor document. Now the design goals have 
moved on, and what we know as GNOME refers to the complete desktop environment, which consists 
of a panel for launching apps, a suite of programs and utilities, programming libraries, and developer 
support features. 


Before you start programming, you need to make sure you've got all the libraries installed. 


Installing the GNOME/GTK+ Development Libraries 


The complete GNOME desktop with its standard applications and the GNOME/GTK+ development 
libraries stretches over more than 60 packages; as a result, installing GNOME from scratch either manually 
or from source code is a daunting prospect. Thankfully, modern Linux distributions have excellent package 
management utilities that make installing GNOME/GTK+ and the development libraries a breeze. 


In Red Hat and Fedora Linux you open the Package Management tool by clicking the Applications menu 
button (in the top left) and choosing Add/Remove Software. When the Package Management tool appears 
(see Figure 16-2), make sure that the GNOME Software Development checkbox is checked. Look in the 
Development area for this setting. 





In this chapter, you will be working with GNOME/GTK+ 2, so make sure your 
installation contains the version 2.x libraries. 
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For distributions that use RPM packages, you should have at least the following RPM packages installed: 


gtk2-2.10.11-7.f£c7.rpm 
gtk2-devel-2.10.11-7.f£c7.rpm 
gtk2-engines-2.10.0-3.fc7.rpm 
libgnome-2.18.0-4.fc7.rpm 
libgnomeui-2.18.1-2.fc7.rpm 
libgnome-devel-2.18.0-4.f£c7.rpm 
libgnomeui-devel-2.18.1-2.£c7.rpm 


In this example, the £c7 in the file names references the Fedora 7 Linux distribution. On your system, 
you may see slightly different names. 


In Debian or Debian-based systems like Ubuntu, you can use apt-get to install the GNOME/GTK+ 
packages from various mirrors — follow the links from http: //www.gnome. org for details. 


Also try out the GTK+ demo application that shows off all the widgets in their finery (see Figure 16-3): 


$ gtk-demo 
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Figure 16-3 


K] 





With each widget, you can see both an Info tab and a Source tab. The Source tab shows actual C source 
code for using the given widget. This can provide a great set of examples. 


‘Try It Out A Plain GtkWindow 


Let’s start programming GTK+ with the simplest of GUI programs: displaying a window. You'll see the 
GTK+ libraries in action, and see how much functionality you get from surprisingly little code. 


1. Type this program and call it gtk1. c: 
#include <gtk/gtk.h> 


int main (int argc, char *argv[]) 
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i 
GtkWidget *window; 


gtk_init (&argc, &argv); 

window = gtk_window_new(GTK_WINDOW_TOPLEVEL) ; 
gtk_widget_show (window) ; 

gtk_main (); 








return 0; 


2: To compile gtk1.c type: 
$ gcc gtkl.c -o gtk1 ‘pkg-config --cflags --libs gtk+-2.0° 


Take care to type backticks, not apostrophes — remember that backticks are instructions to the shell to 
execute and append the output of the enclosed command. 


When you run this program with the following command, your window should pop up (see Figure 16-4): 


$ ./gtk1 








Figure 16-4 


Note that you can move, resize, minimize, and maximize the window. 


How It Works 


You include the necessary GTK+ and related library headers (including GLib) with a single #include 
<gtk/gtk.h> statement. Next, you declare the window to be a pointer to a Gtkwidget. 


Next, to initialize the GTK+ libraries, you must make a call to gtk_init, passing in the command-line 
arguments argc and argv. This gives GTK+ a chance to parse any command-line parameters it needs to 
know about. Note that you must always initialize GTK+ in this way before calling any GTK+ functions. 
The core of the example is the call you make to gtk_window_new. The prototype is 


GtkWidget* gtk_window_new (GtkWindowType type); 


type can take one of two values depending on the purpose of the window: 





Q GTK_WINDOW_TOPLEVEL: A standard framed window 








Q GTK_WINDOW_POPUP: A frameless window suitable for dialog boxes 
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You'll almost always use GTK_WINDOW_TOPLEVEL, because there are far more convenient ways of creat- 
ing dialogs, as you'll see later. 


The call to gtk_window_new sets up the window in memory, so you have a chance to populate it with 
widgets, resize it, change the window title, and so forth, before actually displaying it onscreen. To make 
the window actually appear onscreen, call gtk_widget_show: 


gtk_widget_show (window) ; 
Conveniently, this takes a GtkWidget pointer, so you simply pass in the reference to your window. 


The final call you make is to gtk_main. This key function starts up the interactivity process by passing 
control to GTK+ and doesn’t return until a call to gtk_main_quit is made. As you can see, in gtk1.c this 
never happens, so the application doesn’t end even after the window is closed. Try this out by clicking 

the close icon and seeing that the command prompt doesn’t return. You'll rectify this after you’ve learned 
about signals and callbacks in the next section. For now, quit the application by typing Ctrl+C in the shell 
window you used to launch the gtk1 program. 


Events, Signals, and Callbacks 


All GUI libraries have one thing in common: Some mechanism must exist to execute code in response 
to a user action. A command-line program has the luxury of halting execution to wait for input and can 
then use something like a switch statement to branch execution based on the input. This approach is 
impractical with a GUI application because the application must continually respond to user input; for 
example, it needs to continually update areas of the window. 


Modern windowing systems have systems of events and event listeners that address this problem. The 
idea is that each user input, usually from the mouse or keyboard, triggers an event. A keyboard press 
would trigger a “keyboard event,” for example. Code is then written to listen for these events and to 
execute when such an event is triggered. 


As you saw earlier, the X Window System emits these events, but they aren’t much help to you as a GTK+ 
programmer, because they’re very low level. When a mouse button is clicked, X emits an event that con- 
tains the coordinates of the pointer — what you really need to know is when a user activates a widget. 


Accordingly, GTK+ has its own system of events and event listeners, known as signals and callbacks. 
They’re very easy to use because you can use a very useful feature of C, a pointer to a function, to set 
the signal handler. 

First some definitions: A GTK+ signal is emitted by a GtkObject when something such as user input 
occurs. A function that is connected to a signal, and therefore called whenever that signal is emitted, is 


known as a callback function. 


Note that a GTK+ signal is quite separate from a UNIX signal, discussed in Chapter 11. 
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As a GTK+ programmer, all you need to worry about is writing and connecting callback functions, 
because the signal-emitting code is internal to the particular widget. 


The callback function prototype is typically like this: 

void a_callback_function ( GtkWidget *widget, gpointer user_data); 
You are passed two parameters, the first a pointer to the widget that emitted the signal and the second 
an arbitrary pointer that you pick yourself when you connect the callback. You can use this pointer for 


any purpose. 


Connecting the callback is just as simple. You simply call g_signal_connect and pass in the widget, a 
signal name as a string, a callback function pointer, and your arbitrary pointer: 


gulong g_signal_connect(gpointer *object, const gchar *name, GCallback func, 
gpointer user_data ); 


One point worthy of noting — there are no restrictions in connecting callbacks. You can have multiple 
signals to a single callback function, and multiple callback functions connected to a single signal. You 
can see in detail the signals that each widget emits by reading the GTK+ API documentation. 





Prior to GTK+ 2, the function to connect callback functions was gtk_signal_con- 


nect. This function has been replaced by g_signal_connect and should not be 
used in new code. 





You try out g_signal_connect in your next example. 


Try It Out A Callback Function 


In gtk2. c, add a button to your window and attach the button’s "clicked" signal to your callback 
function to print a short message: 


#include <gtk/gtk.h> 
#include <stdio.h> 


Stata Hage Codin = Mh 


void button_clicked(GtkWidget *button, gpointer data) 
if 

printf("%s pressed %d time(s) \n", (char *) data, ++count); 
} 


int main (int argc, char *argv[]) 
{ 

GtkWidget *window; 

GtkWidget *button; 


gtk_init(&argce, &argv); 
window = gtk_window_new(GTK_WINDOW_TOPLEVEL) ; 
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button = gtk_button_new_with_label ("Hello World!"); 
gtk_container_add(GTK_CONTAINER (window), button) ; 


g_signal_connect (GTK_OBJECT (button), "clicked", 
GTK_SIGNAL_FUNC (button_clicked), 
PRULEOny LO) 

gtk_widget_show(button) ; 

gtk_widget_show (window) ; 


gtk_main (); 


return 0; 


Enter the program source code and save the file under the name gtk2 . c. Compile and link the program 
similarly to the previous gtk1 .c example. When running this program, you'll get a window with a button. 
Each time you click the button, it prints out a short message (see Figure 16-5). 
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Button 1 pressed 3 time(s) 


ix 


[>] 





Hello World! 

















Figure 16-5 


How It Works 


You’ve introduced two new features in gtk2.c: a GtkButton and a callback function. A GtkButton is a 
simple button widget that can contain text, in this case “Hello World,” and emits a signal called "clicked" 
whenever the button is pressed with the mouse. 


The callback function but ton_clicked is connected to the "clicked" signal of the button widget 
using the g_signal_connect function: 


g_signal_connect (GTK_OBJECT (app), "clicked", 
GTK_SIGNAL_FUNC (button_clicked) , 
"Button 1"); 
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Note that the name of the button — "Button 1" — is passed as user data to the callback function. 


The rest of the additional code deals with the button widget, which is created in the same way as the win- 
dow — a call toa gtk_button_new_with_label function — and gtk_widget_show makes it visible. 





To place the button on the window, you call gtk_container_add. This simple function places a 
GtkWidget inside a GtkContainer and takes the container and widget as arguments: 


void gtk_container_add (GtkContainer *container, GtkWidget *widget) ; 


As you saw before, GtkWindow is a child of GtkContainer, so you can cast your window object to a 
GtkContainer type using the GTK_CONTAINER macro: 





gtk_container_add(GTK_CONTAINER (window), button); 


gtk_container_add is great for placing a single widget inside a container, but more often you'll need to 
arrange several widgets in various positions in a window to create a decent interface. GTK+ has special 
widgets just for this purpose, called box or container widgets. 


Packing Box Widgets 


The layout of a GUI is of key importance to its usability and one of the hardest things to get right. The real 
difficulty with arranging widgets is that you can’t rely on all users to have the same screen resolution, or 
to have the same window size, theme, font, or color scheme. What might be a pleasing interface on one 
system might be impossible to read on another. 


To create a GUI that appears uniform on all systems, you need to avoid placing widgets using absolute 
coordinates and instead use a more flexible system of layout. GTK+ has container widgets for this purpose. 
Container widgets allow you to control the layout of widgets within your application windows. Box widgets 
provide a very useful type of container widget. GTK+ offers many other types of container widgets, covered 
in the GTK+ online documentation discussed previously. 


Box widgets are invisible widgets whose job it is to contain other widgets and control their layout. To 
control the size of the individual widgets contained inside the box widget, you specify rules instead of 
coordinates. Because box widgets contain any GtkWidget, and a GtkBox is itself a GtkWidget, you can 
nest box widgets inside one another to create complex layouts. 


There are two main subclasses of GtkBox: 


Ql GtkHBox is a single row horizontal packing box widget. 





Q GtkVBox is a single column vertical packing box widget. 
When the packing boxes are created, you should specify two parameters, homogeneous and spacing: 


GtkWidget* gtk_hbox_new (gboolean homogeneous, gint spacing); 
GtkWidget* gtk_vbox_new (gboolean homogeneous, gint spacing); 
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These parameters control layout for all of the widgets in that particular packing box. homogeneous is a 
boolean that, when set to TRUE, forces contained widgets to occupy equal space, regardless of individual 
size. spacing sets the gap between widgets in pixels. 


Once you've created the packing box, add widgets using gtk_box_pack_start and 
gtk_box_pack_end functions: 


void gtk_box_pack_start (GtkBox *box, GtkWidget *child, 
gboolean expand, gboolean fill, 
guint padding) ; 


void gtk_box_pack_end (GtkBox *box, GtkWidget *child, 
gboolean expand, gboolean fill, 
guint padding) ; 


gtk_box_pack_start adds widgets to the left side of a GtkHBox and to the bottom of a GtkVBox; con- 
versely gtk_box_pack_end from the right and top. Their parameters control the spacing and format of 
each widget within the packing box. 


The following table describes the parameters you can pass to gtk_box_pack_start or 
gtk_box_pack_end. 


Parameter Description 

GtkBox *box The packing box to be filled. 

GtkWidget *child The widget to be placed in the packing box. 

gboolean expand If TRUE, this widget fills all available space shared between the other 


widgets with this flag also set to TRUE. 


gboolean fill If TRUE, this widget will fill the space allocated to it, rather than use it 
as padding around the edges. Only valid when expand is TRUE. 


guint padding Padding size in pixels around widget. 


Let’s take a look at these packing box widgets now and create a more complex user interface, showing 
off nested packing boxes. 


Try It Out Widget Container Layout 


In this example, you lay out some simple GtkLabel widgets using GtkHBox and GtkVBox. Label widgets 
are simple widgets that are useful for displaying short amounts of text. Call this program container.c. 


#include <gtk/gtk.h> 
void closeApp ( GtkWidget *window, gpointer data) 
{ 


gtk_main_quit(); 
} 
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/* Callback allows the application to cancel 


a close/destroy event. (Return TRUE to cancel.) */ 





gboolean delete_event (GtkWidget *widget, GdkEvent *event, gpointer data) 
{ 

printf("In delete_event\n"); 

return FALSE; 
} 


int main (int argc, char *argv[]) 

{ 

kWidget *window; 

kWidget *labell, *label2, *label3; 
kWidget *hbox; 

kWidget *vbox; 


QQQQ 
Ge Gr Gr Gl 














gtk_init(&argce, &argv); 

window = gtk_window_new(GTK_WINDOW_TOPLEVEL) ; 
gtk_window_set_title(GTK_WINDOW (window), "The Window Title"); 
gtk_window_set_position(GTK_WINDOW (window), GTK_WIN_POS_CENTER) ; 
gtk_window_set_default_size(GTK_WINDOW(window), 300, 200); 





g_signal_connect ( GTK_OBJECT (window), "destroy", 
GTK_SIGNAL_FUNC ( closeApp), NULL); 





g_signal_connect ( GTK_OBJECT (window), "delete_event", 
GTK_SIGNAL_FUNC ( delete_event), NULL); 

label1 = gtk_label_new("Label 1"); 

label2 = gtk_label_new("Label 2"); 

label3 = gtk_label_new("Label 3"); 


hbox = gtk_hbox_new TRURO js 
vbox = gtk_vbox_new FALSE, 10); 








k_box_pack_start (GTK_BOX(vbox), label1, TRUE, FALSE, 5); 
k_box_pack_start (GTK_BOX(vbox), label2, TRUE, FALSE, 5); 


g 
g 





k_box_pack_start (GTK_BOX (hbox), vbox, FALSE, FALSE, 5); 
k_box_pack_start (GTK_BOX (hbox), label3, FALSE, FALSE, 5); 





(ar (Gh 





k_container_add(GTK_CONTAINER (window), hbox); 
k_widget_show_all (window); 
k_main (); 











Q 
CEECEE TA 


return 0; 
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When you run this program, you see the layout of label widgets in your window (see Figure 16-6). 


{= The Window Title ToK 
Label 1 
Label 3 


Label 2 











Figure 16-6 


How It Works 
You create two packing box widgets, hbox and vbox. You fill vbox with labe11 and labe12 using 
gtk_box_pack_start, so label2 appears at the bottom because it is added after 1abe11. Next vbox 
itself is added to hbox along with labe13. 


hbox is finally added to the window and is shown onscreen using gtk_widget_show_all. 


The packing box layout is understood best with a diagram, as shown in Figure 16-7. 















































Label 
Label3 
Label2 
vbox 
hbox 
window 
Figure 16-7 


Now that you've looked at widgets, signals, callbacks, and container widgets, you've seen the essentials 
of GTK+. Becoming a knowledgeable GTK+ programmer involves understanding how best to use the 
available widgets. 


GTK+ Widgets 


In this section, we look at the API of the common GTK+ widgets you'll use most often in your applications. 
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GtkWindow 


GtkWindow is the basic element of all GTK+ applications. You’ve used it so far to hold your widgets: 


GtkWidget 
+----GtkContainer 


+----GtkBin 


+----GtkWindow 


There are dozens of GtkwWindow API calls, but here are the functions worthy of special attention: 


GtkWidget* gtk_window_new (GtkWindowType type); 


void 
void 
void 
void 
void 
void 
void 
void 





gtk_window_set_title (GtkWindow *window, const gchar *title); 
gtk_window_set_position (GtkWindow *window, GtkWindowPosition position) ; 
gtk_window_set_default_size (GtkWindow *window, gint width, gint height); 
gtk_window_resize (GtkWindow *window, gint width, gint height); 
gtk_window_set_resizable (GtkWindow *window, gboolean resizable) ; 
gtk_window_present (GtkWindow *window) ; 

gtk_window_maximize (GtkWindow *window) ; 

gtk_window_unmaximize (GtkWindow *window) ; 


As you've just seen, gtk_window_new creates a new, empty window in memory. The window title is 
unset, and the size and screen position of the window are undefined. You will normally populate the 
window with widgets and set up a menu and toolbar before making the window visible onscreen with 
a call to gtk_widget_show. 


The gtk_window_set_title function changes the text of the title bar by informing the window 
manager of the request. 


Note that because it is the window manager, not GTK+, that is responsible for painting the window 
surround, the font, color, and size of the text are dependent on your choice of window manager. 


gtk_window_set_position controls the position of the initial placement onscreen. The position 
parameter can take five values, described in the following table. 


Position Parameter 


GTK 


WIN 


GTK_WIN_ 


GTK_WIN_ 


GTK_WIN_ 


POS_NONE 


POS_CENTER 





T 


POS_MOUSE 


POS_CENTER_ALWAYS 











GTK. 








WIN 











POS_CENTER_ON_PARENT 
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Description 


The window is placed at the discretion of the 
window manager. 


The window is positioned centrally onscreen. 
The window is positioned at the mouse pointer. 
Keeps the window centered regardless of size. 


Sets the window centrally on its parent (useful for 
dialog boxes). 
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gtk_window_set_default_size sets the size of the window onscreen in GTK+ drawing units. Explicitly 
setting the size of the window ensures that the contents of the window aren’t obscured or hidden. To force 
a resize of the window once it’s onscreen, you can use gtk_window_resize. By default, the user is able to 
resize the window by dragging the frame in the usual way. To prevent this, you can call 
gtk_window_set_resizeable set to FALSE. 


To ensure that your window is onscreen and visible to the user — that is, not minimized or hidden — 
gtk_window_present fits the bill. gck_window_present is useful for dialog boxes to make sure they’re 
not minimized when you need some user input. Alternatively, to force maximizing and minimizing you 
have gtk_window_maximize and gtk_window_minimize. 


GtkEntry 


The GtkEntry widget is a single-line text entry widget that is commonly used to enter simple textual 
information, for example an e-mail address, a username, or a hostname. There are API calls that enable 
you to set as well as read the entered text, set the maximum number of allowed characters, and set other 
things to control the positioning and selection of the text: 


GtkWidget 
+----GtkEntry 


GtkEntry can be set to display asterisks (or any other user-definable character) in place of the literal 
typed characters, which can be very useful for entering passwords when you don’t want anybody to 
lean over your shoulder and read the text. 





We'll describe the most useful GtkEnt ry functions: 


GtkWidget* gtk_entry new (void); 

GtkWidget* gtk_entry_new_with_max_length (gint max); 

void gtk_entry_set_max_length (GtkEntry *entry, gint max); 
G_CONST_RETURN gchar* gtk_entry_get_text (GtkEntry *entry) ; 

void gtk_entry_set_text (GtkEntry *entry, const gchar *text); 
void gtk_entry_append_text (GtkEntry *entry, const gchar *text); 
void gtk_entry_prepend_ text (GtkEntry *entry, const gchar *text); 
void gtk_entry_set_visibility (GtkEntry *entry, gboolean visible); 
void gtk_entry_set_invisible_ char (GtkEntry *entry, gchar invch); 
void gtk_entry_set_editable (GtkEntry *entry, gboolean editable); 





You can create a GtkEntry with either gtk_entry_new, or with a fixed maximum length of input text 
with gtk_entry_new_with_max_length. Restricting the input to a certain length saves you the effort 
of validating the input length and possibly having to inform the user that the text is too long. 





To get the contents of the GtkEntry, you call gtk_entry_get_text, which returns a const char 
pointer internal to the GtkEntry (G_CONST_RETURN is a GLib-defined macro). If you want to modify the 
text, or pass it to a function that might modify it, you must copy the string using, for example, strcpy. 








You can manually set and modify the contents of the GtkEntry using the __set_text, _append_text, 
and _modify_text functions. Note that these take const pointers. 
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To use GtkEntry as a password entry box that displays asterisks in place of characters, use 
gtk_entry_set_visibilility passing FALSE as the visible parameter. The invisible character 
can be changed using gtk_entry_set_invisible_char to suit your requirements. 


Try It Out Username and Password Entry 





Now that you’ve seen the GtkEntry functions, let’s look at them in action with a short program. 
entry.c will create a username and password entry window and compare the entered password with 
a secret password. 


1. First define the secret password, cunningly chosen to be secret: 


#include <gtk/gtk.h> 
#include <stdio.h> 
#include <string.h> 


const char * password = "secret"; 


2. You have two callback functions that are called when the window is destroyed and the OK but- 
ton is clicked: 


void closeApp ( GtkWidget *window, gpointer data) 
{ 

gtk_main_quit(); 
} 


void button_clicked (GtkWidget *button, gpointer data) 
{ 
const char *password_text = gtk_entry_get_text (GTK_ENTRY( (GtkWidget *) data)); 


if (strcmp (password_text, password) == 0) 
printf("Access granted!\n"); 
else 


printf ("Access denied! \n"); 


3. In main, the interface is created and laid out, and the callbacks connected. Use hbox and vbox 
container widgets to lay out the label and entry widgets. 


int main (int argc, char *argv[]) 

{ 

kWidget *window; 

kWidget *username_label, *password_label; 
kWidget *username_entry, *password_entry; 
kWidget *ok_button; 

kWidget *hbox1, *hbox2; 

kWidget *vbox; 


QQQQQ0 


gtk_init(&argce, &argv); 


= 


indow = gtk_window_new(GTK_WINDOW_TOPLEVEL) ; 
gtk_window_set_title(GTK_WINDOW (window), "GtkEntryBox") ; 
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gtk_window_set_position(GTK_WINDOW (window), GTK_WIN_POS_CENTER) ; 











gtk_window_set_default_size(GTK_WINDOW(window), 200, 200); 

g_signal_connect ( GTK_OBJECT (window), "destroy", 
GTK_SIGNAL_FUNC ( closeApp), NULL) ; 

username_label = gtk_label_new("Login:") ; 

password_label = gtk_label_new("Password:") ; 

username_entry = gtk_entry_new(); 

password_entry = gtk_entry_new(); 

gtk_entry_set_visibility(GTK_ENTRY (password_entry), FALSE); 

ok_button = gtk_button_new_with_label ("Ok"); 








g_signal_connect (GTK_OBJECT (ok_button), "clicked", 


GTK_SIGNAL_FUNC (button_clicked), password_entry) ; 












































hbox1. = gtk hbox_ new ( TRUE, 5 )? 

hbox2 = gtk_hbox_new ( TRUE, 5 ); 

vbox = gtk_vbox_new ( FALSE, 10); 

gtk_box_pack_start (GTK_BOX (hbox1), username_label, TRUE, FALSE, 5); 
gtk_box_pack_start (GTK_BOX (hbox1), username_entry, TRUE, FALSE, 5); 
gtk_box_pack_start (GTK_BOX (hbox2), password_label, TRUE, FALSE, 5); 
gtk_box_pack_start (GTK_BOX (hbox2), password_entry, TRUE, FALSE, 5); 
gtk_box_pack_start (GTK_BOX(vbox), hboxl, FALSE, FALSE, 5); 
gtk_box_pack_start (GTK_BOX(vbox), hbox2, FALSE, FALSE, 5); 
gtk_box_pack_start (GTK_BOX(vbox), ok_button, FALSE, FALSE, 5); 
gtk_container_add(GTK_CONTAINER (window), vbox) ; 

gtk_widget_show_al1 (window); 

gtk_main (); 

return 0; 


When you run this program, you get a window that appears as in Figure 16-8. 


How It Works 


The program creates two GtkEntry widgets, username_entry and password_entry, and sets 
password_entry with a visibility of FALSE to hide the entered password. It then creates a GtkButton 
with which you connect the "clicked" signal to the button_clicked callback function. 


Once in the callback function, the program retrieves the entered password and compares it to the secret 
password, printing the appropriate message. 


Notice that you have repeated gtk_box_pack_start statements to add the widgets to their containers. 
To reduce this repeated code, you'll define a helper function in later examples. 
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5 ericfj@kayak:/home2/ericfj/writing/Beginning Linux Programming 4th Ed/e| —||0)/x 
File Edit View Terminal Tabs Help 
[ericfj@kayak eric src]$ ./entry [a 


Access denied! 
Access granted! 








GtkEntryBox 
Login: Leonard 
Password: soscoo 
= z Sener 

















Figure 16-8 


GtkSpinButton 


Sometimes you'll want the user to enter a numeric value such as a maximum speed or length of 
device, and in these situations, a GtkSpinButton is ideal. GtkSpinButton restricts a user to entering 
numeric characters only, and you can set the range for allowed values between a lower and upper 
bound. The widget also provides up and down arrows so the user can “spin” the value using only 
the mouse for convenience: 


GtkWidget 
+----GtkEntry 
+----GtkSpinButton 





Again, the API is straightforward, and we'll list the most commonly used calls: 
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GtkWidget* gtk_spin_button_new (GtkAdjustment *adjustment, gdouble climb_rate, 
guint digits); 

GtkWidget* gtk_spin_button_new_with_range (gdouble min, gdouble max, gdouble step); 

void gtk_spin_button_set_digits (GtkSpinButton *spin_button, guint digits); 

void gtk_spin_button_set_increments (GtkSpinButton *spin_button, gdouble step, 
gdouble page); 

void gtk_spin_button_set_range (GtkSpinButton *spin_button, gdouble min, 
gdouble max); 

gdouble gtk_spin_button_get_value (GtkSpinButton *spin_button) ; 

gint gtk_spin_button_get_value_as_int (GtkSpinButton *spin_button) ; 

void gtk_spin_button_set_value (GtkSpinButton *spin_button, gdouble value); 
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To create a GtkSpinButton using gtk_spin_button_new, you first need to create a GtkAdjustment 
object. A GtkAdjustment widget is an abstract object that contains logic to deal with controlling 
bounded values. GtdAdjustment is also used in other widgets, such as GtkHScale and GtkvScale. 


To create a GtkAdjustment, pass in an initial value, lower and upper bounds, and increment sizes: 


GtkObject* gtk_adjustment_new (gdouble value, gdouble lower, gdouble upper, 
gdouble step_increment, gdouble page_increment, 
gdouble page_size); 


The values of step_increment and page_increment set the size of minor and major size increments. In 
the case of GtkSpinButton, the step_increment sets how much the value changes when the arrows are 
clicked. page_increment and page_size are not important when used with GtkSpinButton widgets. 


climb_rate, the second parameter of gtk_spin_button_new, controls how quickly the values “spin” 
when you press and hold the arrow buttons. Finally, digits sets the precision of the widget, so a digit 
of 3 would set the spin button to display 0.00. 





gtk_spin_button_new_with_range is a convenience method that creates a GtkAdjustment for you. 
Simply pass in the lower bound, upper bound, and step rate. 





Reading the current value is easy with gtk_spin_button_get_value, and if you want an integer 
value, you can use gtk_spin_button_get_value_as_int. 





Try It Out GtkSpinButton 


You'll now see a GtkSpinButton in action with a short example. Name this file spin.c. 
#include <gtk/gtk.h> 


void closeApp ( GtkWidget *window, gpointer data) 
{ 

gtk_main_quit(); 
} 


int main (int argc, char *argv[]) 
{ 
GtkWidget *window; 
GtkWidget *spinbutton; 
GtkObject *adjustment; 


gtk_init (&argce, &argv); 

window = gtk_window_new(GTK_WINDOW_TOPLEVEL) ; 

gtk_window_set_default_size ( GTK_WINDOW(window), 300, 200); 

g_signal_connect ( GTK_OBJECT (window), "destroy", 
GTK_SIGNAL_FUNC ( closeApp), NULL) ; 








adjustment gtk_adjustment_new(100.0, 50.0, 150.0, 0.5, 0.05, 0.05); 
spinbutton = gtk_spin_button_new(GTK_ADJUSTMENT (adjustment), 0.01, 2); 
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gtk_container_add(GTK_CONTAINER (window), spinbutton) ; 
gtk_widget_show_all (window) ; 
gtk_main (); 


return 0; 


When you run this program, you get a spin button bounded between 50 and 150 (see Figure 16-9). 





{p6.50 $ 











Figure 16-9 


GtkButton 


You’ve already seen GtkButton in action, but there are more button widgets descended from 
GtkButton that have slightly more functionality and deserve a mention: 


GtkButton 
+----GtkToggleButton 
+----GtkCheckButton 
+----GtkRadioButton 


As you can see from the widget hierarchy, GtkToggleButton is descended directly from GtkButton, 
GtkCheckButton from GtkToggleButton and similarly with GtkRadioButton, each child widget 


specializing in purpose. 


GtkToggleButton 


GtkToggleButton is identical to a GtkButton except in one important regard: GtkToggleButton pos- 
sesses state. That is, it can be on or off. When the user clicks a GtkToggleButton, it emits the "clicked" 


signal in the usual manner and changes (or “toggles”) its state. 
The API for GtkToggleButton is very straightforward: 


GtkWidget* gtk_toggle_button_new (void); 

GtkWidget* gtk_toggle_button_new_with_label (const gchar *label); 

gboolean gtk_toggle_button_get_active (GtkToggleButton *toggle_ button) ; 

void gtk_toggle_button_set_active (GtkToggleButton *toggle_button, 
gboolean is_active); 
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The interesting functions are gtk_toggle_button_get_active and gtk_toggle_button_set_active, 
which you call to read and set the state of the toggle button. An activity of TRUE indicates the 
GtkToggleButton is “on.” 


GtkCheckButton 


GtkCheckButton is a GtkToggleButton in disguise. Instead of the boring, rectangular blob of 
GtkToggleButton, GtkCheckButton appears as an exciting checkbox with text at the side. There are 


no functional differences. 


GtkWidget* gtk_check_button_new (void); 
GtkWidget* gtk_check_button_new_with_label (const gchar *label); 





GtkRadioButton 


This next button is rather different, because it can be grouped with other buttons of the same type. 
GtkRadioButton is one of those buttons that allows you to select only one option at a time from a 
group of options. The name comes from old-style radios that have mechanical buttons that pop back 
out when you press in another button. 


GtkWidget* gtk_radio_ button_new (GSList *group); 

GtkWidget* gtk_radio_button_new_from_widget (GtkRadioButton *group) ; 

GtkWidget* gtk_radio_ button_new_with_label (GSList *group, const gchar *label); 
void gtk_radio_button_set_group (GtkRadioButton *radio_button, GSList *group); 
GSList* gtk_radio_button_get_group (GtkRadioButton *radio_button) ; 














The RadioButton group is represented in a GLib list object, called a GSList. To place radio 

buttons in a group, you can create a GSList and pass it to each button using gtk_radio_button_new 
and gtk_radio_button_get_group. There’s an easier way, however, in the shape of 
gtk_radio_button_new_with_widget, which grabs the GSList out of an existing button for 

you. You'll see this in action in the next example, where you try out different GtkButtons. 











Try It Out GtkCheckButton, GtkToggleButton, and GtkRadioButton 


Enter the following under the file name buttons.c. 
1. First, declare the button pointers as global variables: 


#include <gtk/gtk.h> 
#include <stdio.h> 


GtkWidget *togglebutton; 
GtkWidget *checkbutton; 
GtkWidget *radiobuttonl, *radiobutton2; 


void closeApp ( GtkWidget *window, gpointer data) 


{ 
gtk_main_quit(); 
} 


669 


Chapter 16: Programming GNOME Using GTK+ 


2. Here you define a helper function that packs a GtkWidget and GtkLabel into a GtkHbox and 
then adds this GtkHbox into a given container widget. This helps cut down on repeated code. 


void add_widget_with_label(GtkContainer * box, gchar * caption, GtkWidget * widget) 
{ 

GtkWidget *label = gtk_label_new (caption) ; 

GtkWidget *hbox = gtk_hbox_new (TRUE, 4); 


gtk_container_add(GTK_CONTAINER (hbox), label); 
gtk_container_add(GTK_CONTAINER (hbox), widget); 











gtk_container_add(box, hbox) ; 


3. print_active is another helper function that prints out the current state of the given 
GtkToggleButton with a describing string. It is called from button_clicked, which is a 
callback function attached to the clicked signal of the OK button. Every time this button is 
clicked, you get a printout of the state of the buttons. 


void print_active(char * button_name, GtkToggleButton *button) 


{ 
gboolean active = gtk_toggle_button_get_active (button); 





printf("%s is s\n", button_name, active?"active":"not active"); 


} 


void button_clicked(GtkWidget *button, gpointer data) 
{ 





print_active("Checkbutton", GTK_TOGGLE_BUTTON (checkbutton) ) ; 
print_active("Togglebutton", GTK_TOGGLE_BUTTON(togglebutton) ); 
print_active("Radiobuttonl1", GTK_TOGGLE_BUTTON(radiobutton1) ); 
print_active("Radiobutton2", GTK_TOGGLE_BUTTON (radiobutton2) ) ; 
(oe eucan (( \ai'")) 2 














4. Inmain, you create the button widgets, stack them up in a GtkVBox adding descriptive labels, 
and connect the callback signal to the OK button: 


gint main (gint argc, gchar *argv[]) 


Q 


tkwidget *window; 
tkwidget *button; 
tkwidget *vbox; 


QQ 


gtk_init (&argc, &argv); 

window = gtk_window_new(GTK_WINDOW_TOPLEVEL) ; 
gtk_window_set_default_size(GTK_WINDOW(window), 200, 200); 
g_signal_connect ( GTK_OBJECT (window), "destroy", 
GTK_SIGNAL_FUNC (closeApp), NULL) ; 











button = gtk_button_new_with_label ("Ok"); 
togglebutton = gtk_toggle_button_new_with_label ("Toggle") ; 
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checkbutton = gtk_check_button_new() ; 
radiobuttonl = gtk_radio_button_new(NULL) ; 
radiobutton2 = gtk_radio_button_new_from_widget (GTK_RADIO_BUTTON(radiobutton1) ) ; 


vbox = gtk_vbox_new (TRUE, 4); 

add_widget_with_label (GTK_CONTAINER(vbox), "ToggleButton:", togglebutton) ; 
add_widget_with_label (GTK_CONTAINER(vbox), "CheckButton:", checkbutton) ; 
add_widget_with_label (GTK_CONTAINER(vbox), "Radio 1:", radiobutton1) ; 
add_widget_with_label (GTK_CONTAINER(vbox), "Radio 2:", radiobutton2) ; 
add_widget_with_label (GTK_CONTAINER(vbox), "Button:", button); 


g_signal_connect (GTK_OBJECT (button), "clicked", 
GTK_SIGNAL_FUNC (button_clicked), NULL); 


gtk_container_add(GTK_CONTAINER (window), vbox) ; 
gtk_widget_show_al1 (window); 
gtk_main (); 


return 0; 


Figure 16-10 shows buttons .c in action, with the four common types of GtkButton. 


I 
B ericfj@kayak:/home2/ericfj/writing/Beginning Linux Programming 4th Ed/e -|0| x 
File Edit View Terminal Tabs Help 
[ericfj@kayak eric src]$ ./buttons 
Checkbutton is active 
Togglebutton is active 
Radiobuttonl is not active 
Radiobutton2 is active 





Checkbutton is active = buttons T0% 

















Togglebutton is active P 
Radiobuttonl is active oae UCL page 
Radiobutton2 is not active 
CheckButton: 1 

Radio 1: è 

Radio 2: 

Button: | Ok 
Figure 16-10 


Click OK to see the state of the various buttons. 


This program is a simple example of using the four types of GtkBut ton and shows how you can 

read the state of the GtkToggleButton, GtkCheckButton, and GtkRadioButton using the single 
gtk_toggle_button_get_active. This is one of the great benefits of an object-oriented approach — 
because you don’t need separate get_active functions for each type of button, you can cut down the 
amount of code you need. 
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GtkTreeView 


Up until now, we’ve looked at some of the simple GTK+ widgets, but not all widgets are single-line 
input or display devices. There are, of course, no limits to the complexity of a Gtkwidget, and 
GtkTreeView is a great example of a widget that encapsulates a vast amount of functionality: 


GtkWidget 
+----GtkContainer 
+----GtkTreeView 


GtkTreeView is part of a family of widgets new to GTK+ 2 that creates list and tree views of data of the 
sort you find in a spreadsheet or file manager. Using GtkTreeView, you can create complex views of 
data, mix text, and bitmap graphics, and even input data using GtkEntry widgets, and so forth. 


The quickest way of taking GtkTreeView for a test drive is to fire up the gtk-demo application that 
ships with GTK+. The demo application shows off the capability of each GTK+ widget including 
GtkTreeView, which is shown in Figure 16-11. 
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Figure 16-11 


The GtkTreeView family is made up of four components: 


GtkTreeView: The Tree and List View 
GtkTreeViewColumn: Represents a list or tree column 


GtkCellRenderer: Controls drawing cells 





Coo oOo 





GtkTreeModel: Represents Tree and List data 
The first three make up what is known as the View, and the last is the Model. The concept of separating 


the View from the Model (often called the Model/View/Controller design pattern, or MVC for short) is 
not particular to GTK+, but a design increasingly favored in all programming circles. 
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The key advantage of the MVC design pattern is that data can be rendered simultaneously by different 
views without unnecessary duplication. For example, text editors can have split panes and edit different 
parts of the document without two copies of the document in memory. 


The MVC pattern is also very popular in Web programming because it makes it easy to create a website 
that renders differently in mobile or WAP browsers than it does in desktop browsers, simply by having 
separate View components optimized for each browser type. You can also separate the logic of acquiring 
the data, such as querying a database, from the logic for the user interface. 


We'll start by looking at the Model component, of which GTK+ has two. GtkTreeStore holds multilevel 
data such as a directory hierarchy, and GtkListStore is for flat data. 


To create a GtkTreeStore, pass in the number of columns followed by the type of each column: 


Gtkwidget *store = gtk_tree_store_new (3, G_TYPE_STRING, G_TYPE_INT, 
G_TYPE_BOOLEAN) ; 





Reading, adding, editing, and removing data from the store are done with the aid of GtkTreeIter 
structures. These iterator structures point to nodes in the tree (or rows in a list) and aid in locating and 
manipulating parts of the potentially very large data structure. There are several API calls to get the 
iterator object at various points in a tree, but we'll look at the simplest, gtk_tree_store_append. 


Before you can add any data to the tree store, you need an iterator to point to a new row. 
gtk_tree_store_append fills in a GtkTreeIter object that represents a new row in the tree, 

as either a top-level row (if you pass NULL to the third argument) or as a child row (if you pass the 
iterator of the parent row). 


GtkTreeIter iter; 
gtk_tree_store_append (store, &iter, NULL); 


Once you have an iterator, you can populate the row using gtk_tree_store_set: 


gtk_tree_store_set (store, &iter, 
0, "Def Leppard", 
i, IRE, 
2, TRUE, 
EDE 


You pass the column number and data in pairs, terminated by —1. You’ll use an enum later to make the 
column numbers descriptive. 


To add a branch to this row (a child row), you just need an iterator for the child row that you get by 
calling gtk_tree_store_append again, passing in the top-level row this time: 


GtkTreeIter child; 
gtk_tree_store_append (store, &child, &iter); 


You can read more about GtkTreeStore and GtkListStore functions in the API documentation, so 
let’s move on and look at the GtkTreeView View component. 
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Creating a GtkTreeView is simplicity itself; just pass in the GtkTreeStore or GtkListStore model to 
the constructor: 





GtkWidget *view = gtk_tree_view_new_with_model (GTK_TREE_MODEL (store) ); 





It’s now a case of configuring the widget to display the data exactly as you want it. For each column you 
must define a GtkCel1Renderer and set the data source. You can choose to display only certain data 
columns, for example, or swap the display order of columns. 


GtkCell1Renderer is the object that deals with drawing each cell onscreen, and there are three subclasses 
that deal with text cells, pixmap graphic cells, and togglebutton cells: 


m GtkCellRendererText 


Ü GtkCellRendererPixBuf 








m GtkCellRendererToggle 
You'll use the text renderer in your View, GtkCellRendererText: 


GtkCellRenderer *renderer = gtk_cell_renderer_text_new (); 

gtk_tree_view_insert_column_with_attributes (GTK_TREE_VIEW (view), 
0, 

"This is the colum title", 

renderer, 

terta Oy 

NULL) ; 








Here you create the renderer and pass it to the column insert function. This function enables you to set the 
GtkCel1lRendererText properties in one go, passed as NULL-terminated key/value pairs. The parameters 
are the tree view, the column number, column title, renderer, and renderer properties. You’re setting the 
"text" attribute here, passing in the column number of the data source. GtkCel1RendererText defines 
several other attributes, including underlining, font, size, and so forth. 


You'll see how this works in practice in the next example, where you put a GtkTreeView through its paces. 


Try It Out GtkTreeView 


Enter the following code and name the file tree. c. 


1. Use an enun to label the columns so you can refer to them by name. N_COLUMNS conveniently is 
the total number of columns. 


#include <gtk/gtk.h> 


enum { 
COLUMN_TITLE, 
COLUMN_ARTIST, 
COLUMN_CATALOGUE, 
N_COLUMNS 
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void closeApp ( GtkWidget *window, gpointer data) 


{ 


gtk_main_quit(); 


int main (int argc, char *argv[]) 


{ 


GtkWidget *window; 

GtkTreeStore *store; 
GtkWidget *view; 
G 
G 





tkTreeIter parent_iter, child_iter; 
tkCellRenderer *renderer; 


tk_init(&argc, &argv) ; 

indow = gtk_window_new(GTK_WINDOW_TOPLEVEL) ; 
tk_window_set_default_size ( GTK_WINDOW(window), 300, 200); 
g_signal_connect ( GTK_OBJECT (window), "destroy", 
GTK_SIGNAL_FUNC ( closeApp), NULL); 








Q@=zaQ 





Here you create the tree store, passing in the number and type of each column: 


store = gtk_tree_store_new (N_COLUMNS, G_TYPE_STRING, G_TYPE_STRING, 
G_TYPE_STRING) ; 








The next part adds a parent and child row to the tree: 
gtk_tree_store_append (store, &parent_iter, NULL); 


gtk_tree_store_set (store, &parent_iter, COLUMN_TITLE, "Dark Side of the Moon", 
COLUMN_ARTIST, "Pink Floyd", 
COLUMN_CATALOGUE, "B000024D4P", 
S 








gtk_tree_store_append (store, &child_iter, &parent_iter); 


gtk_tree_store_set (store, &child_iter, COLUMN_TITLE, "Speak to Me", 
SE 


view = gtk_tree_view_new_with_model (GTK_TREE_MODEL (store)); 








Finally, add columns to the view, setting their data source and titles: 


renderer = gtk_cell_renderer_text_new (); 
gtk_tree_view_insert_column_with_attributes (GTK_TREE_VIEW(view) , 
COLUMN_TITLE, 
"Title", renderer, 
"text", COLUMN_TITLE, 
NULL) ; 
gtk_tree_view_insert_column_with_attributes (GTK_TREE_VIEW(view) , 
COLUMN_ARTIST, 
"Artist", renderer, 
"text", COLUMN_ARTIST, 
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NULL) ; 

gtk_tree_view_insert_column_with_attributes (GTK_TREE_VIEW(view) , 
COLUMN_CATALOGUE, 
"Catalogue", renderer, 
"text", COLUMN_CATALOGUE, 
NULL) ; 





gtk_container_add(GTK_CONTAINER (window), view) ; 





gtk_widget_show_all1 (window) ; 
gtk_main (); 


return 0; 


You'll use a GtkTreeView as the core of your CD application, where you'll modify the contents of the 
GtkTreeView as you query the CD database. 


We've finished our tour of GTK+ widgets, and now we'll turn our attention to the other half of the 
story: GNOME. You'll see how to add menus to your application using the GNOME libraries and how 
the GNOME widgets make programming for the GNOME desktop even easier. 


GNOME Widgets 


GTK+ is designed to be desktop neutral; that is, GTK+ doesn’t make any assumptions that it’s running 
in GNOME, or even that it’s running on Linux. The reason behind this is that GTK+ can be ported to run 
on Windows or any other windowing system with relative ease. The upshot of this is that GTK+ lacks 
the means to tie the program into the desktop, such as a means of saving program configuration, dis- 
playing help files, or programming applets (applets are small utilities that run on the edge panels). 


The GNOME libraries include GNOME widgets that extend GTK+ and replace parts of GTK+ with easier- 
to-use widgets. In this section we look at how to program using GNOME widgets. 


Before you use the GNOME libraries, you must initialize them at the start of your programs in the same 
way you did GTK+. You call gnome_program_init just as you do gtk_init for purely GTK+ programs. 


This function takes an app_id and app_version that you use to describe your program to GNOME, 
a module_info that tells GNOME which library module to initialize, command-line parameters, and 
application properties set as a NULL-terminated list of name/value pairs. 


GnomeProgram* gnome_program_init (const char *app_id, const char *app version, 
const GnomeModuleInfo *module_info, 
int argc, char **argv, 
const char *first_property_name, 


ED 
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The optional property list allows you to set things such as the directory to look for bitmap graphics. 


Try It Out A GNOME Window 


Let’s look ata GNOME program now, by looking at the GNOME replacement to GtkWindow, a 
GnomeApp widget. 


Type in this program and call it gnome1. c: 
#include <gnome.h> 
int main (int argc, char *argv[]) 


{ 
GtkWidget *app; 


gnome_program_init ("gnomel", "1.0", MODULE, argc, argv, NULL); 
app = gnome_app_new ("gnomel", "The Window Title"); 
gtk_widget_show(app) ; 

gtk_main (); 

return 0; 


To compile, you need to include the GNOME headers, so pass 1ibgnomeui and 1ibgnome to pkg-config: 
$ gcc gnomel.c -o gnomel ‘pkg-config --cflags --libs libgnome-2.0 libgnomeui-2.0~ 

A GnomeApp widget extends Gtkwindow and makes it easy to add menus, toolbars, and a status bar along 

the bottom. Because it inherits from GtkWindow, you can use any GtkWindow function with a GnomeApp 


widget. Next you'll look at creating menus, and you'll add a status bar in your final example. 


You can use GTK+ to create menus, but GNOME provides helpful structures and macros that make the 
job much easier. The online GTK+ documentation describes how to create menus in GTK+. 


GNOME Menus 


Creating a drop-down menu bar in GNOME is pleasantly simple. Each menu in the menu bar is repre- 
sented by an array of GNOMEUI Info structs with each element in the array corresponding to a single 
menu item. For example, if you have File, Edit, and View menus, you will have three arrays describing 
the contents of each menu. 


Once you've defined each individual menu, you create the menu bar itself by referencing these arrays in 
another array of GNOMEUI Info structs. 


The GNOMEUI Info struct is a little complicated and needs to be explained: 


typedef struct { 
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GnomeUIInfoType type; 
gchar const *label; 
gchar const *hint; 
gpointer moreinfo; 
gpointer user_data; 
gpointer unused_data; 
GnomeUIPixmapType pixmap_type; 
gconstpointer pixmap_info; 
guint accelerator_key; 
GdkModifierType ac_mods; 
GtkWidget *widget; 

} GnomeUIInfo; 


The first item in the struct, type, defines the type of the menu element that follows. It can be one of 
10 GnomeUI InfoTypes defined by GNOME, described in the following table. 





GnomeUlIInfoType Description 
GNOME_APP_UI_ENDOF INFO Denotes that this is last menu item in the array. 
GNOME_APP_UI_ITEM A normal menu item or a radio button if preceded by 


a GNOME_APP_UI_RADIOITEMS entry. 


GNOME_APP_UI_TOGGLEITEM A toggle button or check button menu item. 
GNOME_APP_UI_RADIOITEMS A radio button group. 
GNOME_APP_UI_SUBTREE Denotes this element is a submenu. Set moreinfo to 


point to the submenu array. 


GNOME_APP_UI_SEPARATOR Inserts a separator line in the menu. 
GNOME_APP_UI_HELP Creates a help topic list for use in a Help menu. 
GNOME_APP_UI_BUILDER_DATA Specifies builder data for the following entries. 
GNOME_APP_UI_ITEM_CONFIGURABLE A configurable menu item. 
GNOME_APP_UI_SUBTREE_STOCK Same as GNOME_APP_UI_SUBTREE except that the label 


text should be looked up in the gnome-libs catalog. 

















GNOME_APP_UI_INCLUDE Same as GNOME_APP_UI_SUBTREE except that the 
items are included in the current menu and not as 
a submenu. 


The second and third members of the struct define the text of the menu item and the pop-up hint. (The hint 
is shown in the status bar at the bottom of the window.) 











The purpose of moreinfo depends on type. For ITEM and TOGGLEITEM, it points to the callback function 
to be called when the menu item is activated. For RADIOITEMS it points to an array of GnomeUIInfo 
structs that are grouped radio buttons. 
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user_data is an arbitrary pointer passed to the callback function. pixmap_type and pixmap_info 
allow you to add a bitmap icon to the menu item, and accelerator_key and ac_mods help you define 
a keyboard shortcut. 


Finally, widget is used to internally hold the menu item widget pointer by the menu creation function. 


Try It Out GNOME Menus 


You can try out menus with this short program. Call it menu1 .c. 
#include <gnome.h> 


void closeApp ( GtkWidget *window, gpointer data) 
{ 

gtk_main_quit(); 
} 


1. Define a callback function for the menu items called item_clicked: 


void item_clicked(GtkWidget *widget, gpointer user_data) 
{ 

printf ("Item Clicked!\n"); 
} 


2. Next are the menu definitions. You have a submenu, top-level menu, and a menu bar array: 


static GnomeUIInfo submenu[] = { 
{GNOME_APP_UI_ITEM, "SubMenu", "SubMenu Hint", 
GTK_SIGNAL_FUNC(item_clicked), NULL, NULL, 0, NULL, 0, 0, NULL}, 
{GNOME_APP_UI_ENDOFINFO, NULL, NULL, NULL, NULL, NULL, 0, NULL, 0, 0, NULL} 
Wy 





static GnomeUIInfo menu[] = { 

{GNOME_APP_UI_ITEM, "Menu Item 1", "Menu Hint", 

NULL, NULL, NULL, 0, NULL, 0, 0, NULL}, 

{GNOME_APP_UI_SUBTREE, "Menu Item 2", "Menu Hint", submenu, 

NULL, NULL, 0, NULL, 0, 0, NULL}, 

{GNOME_APP_UI_ENDOFINFO, NULL, NULL, NULL, NULL, NULL, 0, NULL, 0, 0, NULL} 
Ig 








static GnomeUIInfo menubar[] = { 

{GNOME_APP_UI_SUBTREE, "Toplevel Item", NULL, menu, NULL, 

NUL 05 SNUG 04) Oy Ria} 

{GNOME_APP_UI_ENDOFINFO, NULL, NULL, NULL, NULL, NULL, 0, NULL, 0, 0, NULL} 
Ny 





3.  Inmain, you deal with the usual initialization and then create your GnomeApp widget and set 
the menus: 


int main (int argc, char *argv[]) 


{ 
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GtkWidget *app; 


gnome_program_init ("gnomel", "0.1", LIBGNOMEUI_MODULE, 
argc, argv, 
GNOME_PARAM NONE) ; 

app = gnome_app_new("gnomel", "Menus, menus, menus"); 


gtk_window_set_default_size ( GTK_WINDOW(app), 300, 200); 
g_signal_connect ( GTK_OBJECT (app), "destroy", 
GTK_SIGNAL_FUNC ( closeApp), NULL); 








gnome_app_create_menus ( GNOME_APP(app), menubar) ; 
gtk_widget_show(app) ; 


gtk_main(); 
return 0; 


Try running menu1 and see the menu bar, submenu, and callback GNOME menu in action, as shown in 
Figure 16-12. 


(m Menus, menus, menus 





‘Toplevel Item | 
Menu Item 1 


Menu Item 2 J| SubMenu 








Figure 16-12 


The GnomeUIInfo struct is hardly programmer-friendly, given that it consists of 11 entries, most of which 
are normally NULL or zero valued. It’s quite easy to make a mistake typing them in, and it’s difficult to tell 
one field from another in a long array of items. To improve the situation, GNOME defines macros to take 
out the hard work of writing the structs by hand. These macros also add icons and keyboard accelerators 
for you, all for no cost. In fact, there’s rarely any reason to use anything but these macros. 


There are two sets of macros, the first of which defines individual menu items. They take two parameters, 
the callback function pointer and user data. 


#include <libgnomeui/1libgnomeui.h> 


#define GNOMEULINFO_MENU_OPEN_ITEM (cb, data) 
#define GNOMEUIINFO_MENU_SAVE_ITEM (cb, data) 
#define GNOMEUIINFO_MENU_SAVE_AS_ITEM (cb, data) 
#define GNOMEULIINFO_MENU_PRINT_ITEM (cb, data) 
#define GNOMEUIINFO_MENU_PRINT_SETUP_ITEM(cb, data) 
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#define GNOMEULIINFO_MENU_CLOSE_ITEM (cb, data) 
#define GNOMEULIINFO_MENU_EXIT ITEM (cb, data) 
#define GNOMEULIINFO_MENU_QUIT_ITEM (cb, data) 
#define GNOMEUIINFO_MENU_CUT_ITEM (cb, data) 
#define GNOMEULINFO_MENU_COPY_ITEM (cb, data) 
#define GNOMEULIINFO_MENU_PASTE_ ITEM (cb, data) 
#define GNOMEULINFO_MENU_SELECT_ALL ITEM(cb, data) 
-.. etc 


And the second set is for top-level definitions to which you simply pass the array: 


#define GNOMEUIINFO_MENU_FILE_TREE (tree) 
#define GNOMEUIINFO_MENU_EDIT_TREE (tree) 
#define GNOMEUIINFO_MENU_VIEW_TREE (tree) 
#define GNOMEUIINFO_MENU_SETTINGS_TREE (tree) 
#define GNOMEUIINFO_MENU_FILES_TREE (tree) 
#define GNOMEUIINFO_MENU_WINDOWS_TREE (tree) 
#define GNOMEUIINFO_MENU_HELP_TREE (tree) 
#define GNOMEUIINFO_MENU_GAME_TREE (tree) 


Try It Out Menus with GNOME Macros 


In this example, you make use of these menus and see how the macros work. Make the following changes 
to menu1 .c, and call this menu2 . c. (For simplicity, the menu choices in this example do not define callback 
functions. The purpose here is just to show the convenience of the GNOME menu macros.) 


#include <gnome.h> 


static GnomeUIInfo filemenu[] = { 

GNOMEULINFO_MENU_NEW_ITEM ("New", "Menu Hint", NULL, NULL ), 
GNOMEUIINFO_MENU_OPEN_ITEM (NULL, NULL), 
GNOMEULINFO_MENU_SAVE_AS_ITEM (NULL, NULL), 
GNOMEUIINFO_SEPARATOR, 
GNOMEUIINFO_MENU_EXIT_ITEM (NULL, NULL), 
GNOMEUIINFO_END 


























3 


static GnomeUIInfo editmenu[] = { 

GNOMEULIINFO_MENU_FIND_ITEM (NULL, NULL), 
GNOMEUIINFO_END 

yy 


static GnomeUIInfo menubar[] = { 
GNOMEULINFO_MENU_FILE_TREE (filemenu) , 

GNOMEULINFO_MENU_EDIT_TREE (editmenu) , 
GNOMEUITINFO_END 

Ig 








int main (int argc, char *argv[]) 
{ 
GtkWidget *app, *toolbar; 


gnome_program_init ("gnomel", "0.1", LIBGNOMEUI_MODULE, 
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argc, argv, 

GNOME_PARAM_NONE) ; 
app = gnome_app_new("gnomel", "Menus, menus, menus"); 
gtk_window_set_default_size ( GTK_WINDOW(app), 300, 200); 
gnome_app_create_menus ( GNOME_APP(app), menubar) ; 








gtk_widget_show(app) ; 


gtk_main(); 
return 0; 


} 


By using the 1ibgnomeui macros in menu2 .c, you've significantly reduced the code you need to type 
and made the menu code much more readable. The macros save you time and effort when creating 
menus and make the wording, keyboard shortcuts, and icons consistent with other GNOME applica- 
tions. Try to use them in your applications whenever you can. 


Figure 16-13 shows menu3 . c in action with the now standardized GNOME menu items. 


(= Menus, menus, menus 
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New Ctri+N 
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J Quit Ctri+Q 








Figure 16-13 


Dialogs 


An important part of any GUI application is interacting with and informing users of important events. 
Usually, you'll create a temporary window with OK and Cancel buttons for this, and if the information 
is important enough to require an immediate response, such as deleting a file, you'll want to block access 
to all other windows until the user has made a choice (such windows are called modal dialogs). 


What we've described here is a dialog, and GTK+ provides special dialog widgets that are descended 
from GtkwWindow to make your programming job that much easier. 


GtkDialog 


As you can see, GtkDialog is a child of Gtkwindow and therefore inherits all its functions and properties: 


GtkwWindow 
+----GtkDialog 
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GtkDialog divides the window into two areas, one for widget content and one for buttons that run 
along the bottom. You can specify the buttons you want as well as other dialog settings when you create 
the dialog box. 


GtkWidget* gtk_dialog_new_with_buttons (const gchar *title, 
GtkWindow *parent, 
GtkDialogFlags flags, 
const gchar *first_button_text, 


ssa)? 





This function creates a dialog window complete with a title and buttons. The second parameter, 
parent, should point to the main window of your application so that GTK+ can make sure the dialog 
stays attached to the window and is minimized when the main window is minimized. 


flags determines the combination of properties the dialog can take: 


m) GTK_DIALOG_MODAL 


m) GTK_DIALOG_DESTROY_WITH_PARENT 








Q GTK_DIALOG_NO_SEPARATOR 


You can combine the flags using the bitwise OR operator; for example, 
(GTK_DIALOG_MODAL|GTK_DIALOG_NO_SEPARATOR) is both a modal dialog and one with no separator 
line between the main window area and the button area. 


The remaining parameters are a NULL-terminated list of buttons and corresponding response code. You'll 
see exactly what this response code means when you see gtk_dialog_run. Normally you'll pick but- 
tons from the long list of stock buttons that GTK+ defines as you get ready-made icons in the buttons. 


Here’s how you would create a dialog with OK and Cancel buttons that return GTK_RESPONSE_ACCEPT 
and GTK_RESPONSE_REJECT when those respective buttons are clicked: 





GtkWidget *dialog = gtk_dialog_new_with_buttons ("Important question", 
parent_window, 
GTK_DIALOG_DESTROY_WITH_PARENT, 
GTK_STOCK_OK, GTK_RESPONSE_ACCEPT, 
GTK_STOCK_CANCEL, GTK_RESPONSE_REJECT, 
NULL) ; 




















We’ve chosen to have two buttons here, but there’s no limit to the number of buttons you can have in the 
dialog. Furthermore, you can select from a number of response type flags. The accept and reject flags are 
not used by standard GNOME and are therefore available for you to use in your applications as you 
wish. (Keep in mind that accept ought to mean accept in your application.) Other possibilities here 
include the OK and CANCEL responses shown the GtkResponseType enum in the following section. 


Naturally, you'll need to add content to your dialog, and for this GtkDialog contains a ready-made 
GtkVBox to populate with widgets. You get a pointer directly from the object: 


GtkWidget *vbox = GTK_DIALOG(dialog) ->vbox; 


You use this GtkVBox in the usual way, with gtk_box_pack_start or something similar. 
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Once you've created a dialog box, the next step is to present it to the user and wait for a response. This 
can be done in one of two ways: in a modal fashion, which blocks all input except to the dialog box, or a 
nonmodal way, which treats the dialog the same as any other window. Let’s look at running a modal 
dialog first. 


Modal Dialog Box 


A modal dialog box forces the user to respond before any other action can take place. It’s useful in 
situations where the user is about to do something with serious repercussions or to report errors and 
warning messages. 


You can make a dialog box modal by setting the GTK_DIALOG_MODAL flag and calling gtk_widget_show, 
but there’s a better way. gtk_dialog_run does the hard work for you by stopping further program exe- 
cution until a button is pressed. 


When the user presses a button (or the dialog is destroyed), gtk_dialog_run returns with an int result 
that indicates which button the user pressed. GTK+ usefully defines an enum to describe the possible values: 


typedef enum 

{ 
GTK_RESPONSE_NONE = -1, 
GTK_RESPONSE_REJECT = -2, 
GTK_RESPONSE_ACCEPT = -3, 


GTK_RESPONSE_OK = -5, 
GTK_RESPONSE_CANCEL = -6, 
GTK_RESPONSE_CLOSE = -7, 
GTK_RESPONSE_YES = -8, 
GTK_RESPONSE_NO = -9, 
GTK_RESPONSE_APPLY = -10, 


GTK_RESPONSE_HELP 
} GtkResponseType; 


1 
I 
e 
H 





Now we can explain the result code passed in gtk_dialog_new_with_buttons — the result code is a 
GtkResponseType that gtk_dialog_run returns when that button is pressed. You get a result of 
GTK_RESPONSE_NONE if the dialog is destroyed (this happens if the user clicks the close icon, for example). 


The switch construction is ideal for calling the appropriate logic: 


GtkWidget *dialog = create_dialog(); 
int result = gtk_dialog_run(GTK_DIALOG (dialog) ) ; 














switch (result) 
{ 
case GTK_RESPONSE_ACCEPT: 
delete_file(); 
break; 
case GTK_RESPONSE_ REJECT: 
do_nothing() ; 
break; 
default: 
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dialog_was_cancelled (); 
break; 

} 

gtk_widget_destroy (dialog); 


That’s all there is to simple modal dialogs in GTK+. As you can see, there’s very little code involved or 
effort expended. All you do at the end is tidy up with a gtk_widget_destroy. 


Things aren’t so straightforward, however, when you want a nonmodal dialog box. You can’t use 
gtk_dialog_run — instead you must connect callback functions to the dialog buttons. 


Nonmodal Dialogs 


You’ve seen how to use gtk_dialog_run to create a modal (blocking) dialog. Nonmodal dialogs work 
slightly differently, although you create them in the same way. Instead of calling gtk_dialog_run, you 
connect a callback function to the GtkDialog "response" signal that is emitted when a button is clicked 
or the window is destroyed. 


Connecting the callback signal is done in the usual way, with the difference being that the callback function 
has an extra response argument that plays the same role as the return value of gtk_dialog_run. This code 
snippet shows the basic use of a nonmodal dialog: 


void dialog_button_clicked (GtkWidget *dialog, gint response, gpointer user_data) 
{ 
switch (response) 


{ 


case GTK_RESPONSE_ACCEPT: 
do_stuff(); 
break; 

case GTK_RESPONSE_REJECT: 
do_nothing() ; 
break; 

default: 
dialog_was_cancelled (); 
break; 











} 
gtk_widget_destroy (dialog); 
} 


int main() 


{ 
GtkWidget *dialog = create_dialog(); 


g_signal_connect ( GTK_OBJECT (dialog), "response", 
GTK_SIGNAL_FUNC (dialog_button_clicked), user_data ); 





gtk_widget_show(dialog) ; 
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With nonmodal dialogs, complications can arise because the user isn’t compelled to respond instantly 
and can minimize and forget about the dialog. You need to consider what to do if the user tries to open 
the dialog a second time before closing the first instance. What you need to do is check if the dialog 
pointer is NULL, and if not to reshow the existing dialog by calling gtk_window_present. You can see 
this in action in the “CD Database Application” section near the end of this chapter. 


GtkMessageDialog 


For very simple dialog boxes, even GtkDialog is unnecessarily complicated: 


GtkDialog 
+----GtkMessageDialog 


With GtkMessageDialog, you can create a message dialog box in a single line of code. 





GtkWidget* gtk_message_dialog_new (GtkWindow *parent, GtkDialogFlags flags, 
GtkMessageType type, 
GtkButtonsType buttons, 
const gchar *message_format, 


sahi 


This function creates a dialog complete with icons, a title, and configurable buttons. The parameter type 
sets the stock icon and title of the dialog according to its intended purpose; for instance, the warning 
type has a warning triangle icon. There are four possible values to cover the simple dialog types you 
most often come across: 

GTK_MESSAGE_INFO 

GTK_MESSAGE_WARNING 


GTK_MESSAGE_QUESTION 











DODO 





GTK_MESSAGE_ERROR 











(You can also select a GTK_MESSAGE_OTHER value, used in cases where the preceding dialog types don’t 
apply.) With a GtkMessageDialog, you can pass a GtkButtonsType rather than list each button indi- 
vidually, as described in the following table. 


GtkButtonsType Description 
GTK_BUTTONS_OK An OK button 
GTK_BUTTONS_CLOSE A Close button 
GTK_BUTTONS_CANCEL A Cancel button 
GTK_BUTTONS_YES_NO Yes and No buttons 
GTK_BUTTONS_OK_CANCEL OK and Cancel buttons 
GTK_BUTTONS_NONE No buttons 
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All that remains is the text of the dialog, which you can make up from a substituted string in the same 
way you do with printf. In this example, you ask the user if she is sure she wants to delete a file: 


GtkWidget *dialog = gtk_message_dialog_new (main_window, 
GTK_DIALOG_DESTROY_WITH_PARENT, 
GTK_MESSAGE_QUESTION, 
GTK_BUTTONS_YES_NO, 
"Are you sure you wish to delete %s?", 
filename) ; 

result = gtk_dialog_run (GTK_DIALOG (dialog) ); 

gtk_widget_destroy (dialog); 














This dialog appears like that in Figure 16-14. 





Q Are you sure you wish to delete important.txt? 








Figure 16-14 


GtkMessageDialog is the simplest way of communicating information or asking yes/no type questions. 
You'll make use of them in the following section, when you put your knowledge to use by creating a GUI 
for your CD application. 


CD Database Application 


In the previous chapters you’ve developed a CD database with MySQL and a C interface. You'll now 
see how easy it is to put a GUI front end using GNOME/GTK+, and how quickly you can develop a rich 
user interface. 


You must have the MySQL database and the MySQL developer's libraries installed to try out the example 
CD database application, the same requirement as the CD database application in Chapter 8. 


For the sake of brevity and clarity you'll develop a basic, bare-bones interface that implements only 

a subset of the features — you won’t allow adding of track information to CDs or deleting of CDs, for 
example. You'll see the widgets that were covered in this chapter in action in your application so that 
you can see how they are used in a real-life situation. 


The key features you'll code are 


Q Logging on to the database from the GUI 
Q Searching for a CD 
Q Displaying CD and track information 
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Q Adding a CD to the database 


Q = Creating an About window 





Q Confirming when the user wishes to quit 


You'll divide your code into three source files that share a common header file, cdapp_gnome .h. The 
source files will separate the functions that create windows and dialogs — interface generating functions — 
from callback functions. 


Try It Out cdapp_gnome.h 


First look at cdapp_gnome .h and see the functions that you'll be implementing. 


1. Include the GNOME headers and the header file for the interface functions you developed in 
Chapter 8. This example program uses the app_mysq1 .h and app_mysq1 .c files from Chapter 8, 
along with the same database created in that chapter. 


#include <gnome.h> 
#include "app_mysql.h" 


2. The enum labels the columns of the GtkTreeView widget that you'll use to display the CDs 
and tracks: 


enum { 
COLUMN_TITLE, 
COLUMN_ARTIST, 
COLUMN_CATALOGUE, 
N_COLUMNS 

He 








3. You have three window-creation functions in interface.c: 
GtkWidget *create_main_window() ; 
GtkWidget *create_login_dialog(); 
GtkWidget *create_addcd_dialog(); 


4. Callback functions for the menu items, toolbar, dialog buttons, and search button are in 
callbacks.c: 


/* Callback to quit application */ 
void quit_app( GtkWidget * window, gpointer data); 


/* Callback useful for confirming exit before quitting */ 
gboolean delete_event_handler ( GtkWidget *window, GdkEvent *event, gpointer data); 


/* Callback connected to 'response' signal of addcd dialog */ 
void addcd_dialog_button_clicked (GtkDialog * dialog, gint response, 
gpointer userdata) ; 


/* Callback for menu and toolbar 'Add CD' button */ 
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void on_addcd_activate (GtkWidget *widget, gpointer user_data) ; 


/* Callback for menu 'About' button */ 
void on_about_activate (GtkWidget *widget, gpointer user_data); 


/* Callback for search button */ 
void on_search_button_clicked (GtkWidget *widget, gpointer userdata) ; 


Try It Out interface.c 


Next, take a look first at interface.c, where you define the windows and dialogs you use in the 
application. 


1. First, some widget pointers that you refer to in callbacks.c and main.c: 
#include "app_gnome.h" 


GtkWidget *treeview; 
GtkWidget *appbar; 
GtkWidget *artist_entry; 
GtkWidget *title_entry; 
GtkWidget *catalogue_entry; 
GtkWidget *username_entry; 
GtkWidget *password_entry; 


2. app is the main window pointer that has file scope: 
static GtkWidget *app; 

3.  Definea helper function that adds a widget with given label text to a container: 
void add_widget_with_label ( GtkContainer *box, gchar *caption, GtkWidget *widget) 
{ 


GtkWidget *label = gtk_label_new (caption) ; 
GtkWidget *hbox = gtk_hbox_new (TRUE, 4); 





gtk_container_add(GTK_CONTAINER (hbox), label) ; 
gtk_container_add(GTK_CONTAINER (hbox), widget) ; 








gtk_container_add(box, hbox) ; 


4. The menubar definitions use GNOMEULINFO macros for convenience: 





static GnomeUIInfo filemenu[] = 
{ 
GNOMEULIINFO_MENU_NEW_ITEM ("_New CD", NULL, on_addcd_activate, NULL), 
GNOMEUIINFO_SEPARATOR, 
GNOMEULINFO_MENU_EXIT_ITEM (close_app, NULL), 
GNOMEUTINFO_END 
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static GnomeUIInfo helpmenu[] = 

if 
GNOMEULINFO_MENU_ABOUT_ITEM (on_about_activate, NULL), 
GNOMEULIINFO_END 








Hg 


static GnomeUIInfo menubar[] = 
{ 





GNOMEUIINFO_MENU_FILE_TRE 
GNOMEUI INFO_MENU_HELP_TRE] 
GNOMEUIINFO_END 


(filemenu) , 
(helpmenu) , 











a 
E 





Pe 


5. Here you create the main window, add menu and toolbar, set its size, center onscreen, and 


assemble the widgets that make up the interface. Note that the function doesn’t show the win- 


dow onscreen, but returns a pointer to the window instead. 


GtkWidget * create_main_window() 
{ 

kWidget *toolbar; 

kWidget *vbox; 

kWidget *hbox; 

kWidget *label; 

kWidget *entry; 

kWidget *search_button; 
kWidget *scrolledwindow; 
kCellRenderer *renderer; 








QAANQNDAAAA 
Cia or oe). “fine he Ciera a 


app = gnome_app_new ("GnomeCD", "CD Database") ; 


gtk_window_set_position ( GTK_WINDOW( app), GTK_WIN_POS_CENTER) ; 
gtk_window_set_default_size ( GTK_WINDOW( app ), 540, 480); 





gnome_app_create_menus (GNOME_APP (app), menubar) ; 
6. Create the toolbar using GTK+ stock icons and connect the callback functions: 


toolbar = gtk_toolbar_new (); 
gnome_app_add_toolbar (GNOME_APP (app), GTK_TOOLBAR (toolbar), "toolbar", 
BONOBO_DOCK_ITEM_BEH_ EXCLUSIVE, 
BONOBO DOCK TOP, cl. (0, 0E 
gtk_container_set_border_width (GTK_CONTAINER (toolbar), 1); 
gtk_toolbar_insert_stock (GTK_TOOLBAR (toolbar), 








"gtk-add", 

"Add new CD", 

NULL, GTK_SIGNAL_FUNC (on_addcd_activate), 
NULL, -1); 


gtk_toolbar_insert_space (GTK_TOOLBAR (toolbar), 1); 
gtk_toolbar_insert_stock (GTK_TOOLBAR (toolbar), 
"gtk-quit", 
"Quit the Application", 
NULL, GTK_SIGNAL_FUNC (on_quit_activate), 
NULL, -1); 




















7. 


10. 
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Here you create widgets that you'll use to search for a CD: 


label = gtk_label_new("Search String:"); 
entry = gtk_entry_new (); 
search_button = gtk_button_new_with_label ("Search"); 





gtk_scrolled_window provides scrollbars to allow a widget (in this case a GtkTreeView) to 
expand beyond the window size: 


scrolledwindow = gtk_scrolled_window_new (NULL, NULL); 

gtk_scrolled_window_set_policy (GTK_SCROLLED_WINDOW (scrolledwindow) , 
GTK_POLICY_AUTOMATIC, 
GTK_POLICY_AUTOMATIC) ; 











Next, arrange the interface using container widgets in the usual way: 


gtk_vbox_new 
gtk_hbox_new 


(FALSE, 0); 

(FALSE, 0); 

gtk_box_pack_start (GTK_BOX (vbox), hbox, FALSE, FALSE, 5); 

gtk_box_pack_start (GTK_BOX ), label, FALSE, FALSE, 5); 

gtk_box_pack_start (GTK_BOX (hbox), entry, TRUE, TRUE, 6); 
(G ) 
(G' ) 


vbox 
hbox 





gtk_box_pack_start TK BOX , search_button, FALSE, FALSE, 5); 
gtk_box_pack_start TK BOX @) 2 








, scrolledwindow, TRUE, TRUE 


Then create the GtkTreeView widget, add three columns, and place it in the GtkScrol1ledWindow: 


treeview = gtk_tree_view_new(); 

renderer = gtk_cell_renderer_text_new (); 
gtk_tree_view_insert_column_with_attributes (GTK_TREE_VIEW(treeview) , 
COLUMN_TITLE, 
"Title", renderer, 
"text", COLUMN_TITLE, 
NULL) ; 
gtk_tree_view_insert_column_with_attributes (GTK_TREE_VIEW(treeview) , 
COLUMN_ARTIST, 
"Artist", renderer, 
"text", COLUMN_ARTIST, 
NULL) ; 
gtk_tree_view_insert_column_with_attributes (GTK_TREE_VIEW(treeview) , 
COLUMN_CATALOGUE, 
"Catalogue", renderer, 
"text", COLUMN_CATALOGUE, 
NULL) ; 









































gtk_tree_view_set_search_column (GTK_TREE_VIEW (treeview), 
COLUMN_TITLE) ; 








gtk_container_add (GTK_CONTAINER (scrolledwindow), treeview) ; 


Finally, set the contents of the main window, add a GnomeAppbar, and connect the necessary 
callbacks: 


gnome_app_set_contents (GNOME_APP (app), vbox); 
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appbar = gnome_appbar_new (FALSE, TRUE, GNOME_PREFERENCES_NEVER) ; 
gnome_app_set_statusbar (GNOME_APP (app), appbar) ; 








gnome_app_install_menu_hints (GNOME_APP (app), menubar) ; 








g_signal_connect (GTK_OBJECT (search_button), "clicked", 
GTK_SIGNAL_FUNC (on_search_button_clicked) , 
entry); 





g_signal_connect (GTK_OBJECT(app), "delete_event", 
GTK_SIGNAL_FUNC ( delete_event_handler ), 
NULL) ; 





g_signal_connect (GTK_OBJECT(app), "destroy", 
GTK_SIGNAL_FUNC ( quit_app ), NULL); 


return app; 


12. The next function creates a simple dialog box that enables you to add a new CD to the database. It 
consists of entry boxes for the artist, title, and catalogue fields, as well as OK and Cancel buttons: 


GtkWidget *create_addcd_dialog() 

{ 
artist_entry = gtk_entry_new/(); 
title_entry = gtk_entry_new(); 
catalogue_entry = gtk_entry_new(); 


GtkWidget *dialog = gtk_dialog_new_with_buttons ("Add CD", 
app, 
GTK_DIALOG_DESTROY_WITH_PARENT, 
GTK_STOCK_OK, 
GTK_RESPONSE_ACCEPT, 
GTK_STOCK_CANCEL, 
GTK_RESPONSE_REJECT 
NULL) ; 

















add_widget_with_label ( GTK_CONTAINER (GTK_DIALOG (dialog) ->vbox) , 
DAnte PSU ante St entry), 

add_widget_with_label ( GTK_CONTAINER (GTK_DIALOG (dialog)->vbox), 
"Title", title_entry); 

add_widget_with_label ( GTK_CONTAINER (GTK_DIALOG (dialog) ->vbox) , 


"Catalogue", catalogue_entry) ; 











g_signal_connect ( GTK_OBJECT (dialog), "response", 
GTK_SIGNAL_FUNC (addcd_dialog_button_clicked), NULL); 


return dialog; 
} 


13. The database requires the user to log in before she can query it, so this function creates a dialog 
to enter the username and password: 


GtkWidget *create_login_dialog() 
{ 
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GtkWidget *dialog = gtk_dialog_new_with_buttons ("Database Login", 


username_entry 
password_entry 





app, 
GTK_DIALOG_MODAL, 
GTK_STOCK_OK, 
GTK_RESPONSE_ACCEPT 
GTK_STOCK_CANCEL, 
GTK_RESPONSE_REJECT, 
NULL) ; 


E 














= gtk_entry_new(); 
= gtk_entry_new(); 





gtk_entry_set_visibility(GTK_ENTRY (password_entry), FALSE); 


add_widget_with_label ( GTK_CONTAINER 


add_widget_with_label ( GTK_CONTAINER 


(GTK_DIALOG (dialog)->vbox) , "Username", 
username_entry) ; 
(GTK_DIALOG (dialog)->vbox) , "Password", 
he 








password_entry 





gtk_widget_show_all(GTK_WIDGET (GTK_DIALOG (dialog) ->vbox) ) ; 








return dialog; 


Try It Out 


callbacks.c 


The file callbacks .c contains the functions set up as callbacks for the UI widgets. 


1. First, you need to include the header file and reference some global variables defined in 
interface.c so that you can read and update certain widget properties: 


#include "app_gnome.h" 


extern 
extern 
extern 
extern 
extern 
extern 


static 


G 
G 
G 
G 
G 
G 


tkwidge 
tkwWidge 
tkwWidge 
tkwidge 
tkwWidge 
tkwWidge 





G 


tkwidge 





*treeview; 

*app; 

*appbar; 
*artist_entry; 
*title_entry; 
*catalogue_entry; 


*addcd_dialog; 


2. Inquit_app you call database_end to tidy up and close the database before quitting: 


void quit_app( GtkWidget *window, gpointer data) 


{ 


database_end() 
gtk_main_quit ( 


} 


Ng 
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3. The next function pops up a simple dialog box to confirm that you want to exit the application, 
returning the response as a gboolean: 


gboolean confirm_exit() 
{ 
gint result; 
GtkWidget *dialog = gtk_message_dialog_new (NULL, 
GTK_DIALOG_MODAL, 
GTK_MESSAGE_QUESTION, 
GTK_BUTTONS_YES_NO, 
"Are you sure you want to quit?"); 




















result = gtk_dialog_run (GTK_DIALOG (dialog) ); 
gtk_widget_destroy (dialog); 





return (result == GTK_RESPONSE_YES) ; 


4. delete_event_handler is a callback function that you connect to the Gdk delete event 
of the main window. The event is emitted when you attempt to close a window, but critically 
before the GTK+ destroy signal is sent. 


gboolean delete_event_handler ( GtkWidget *window, GdkEvent *event, gpointer data) 
{ 


return !confirm_exit(); 


5. The next function is called when a button is clicked on the add CD dialog. If you click OK, the 
program copies the strings into a non-const char array and passes the data in it to the MySQL 
interface function add_cd: 


void addcd_dialog_button_clicked (GtkDialog * dialog, gint response, 
gpointer userdata) 
{ 
const gchar *artist_const; 
const gchar *title_const; 
const gchar *catalogue_const; 
gchar artist[200]; 
gchar title[200]; 
gchar catalogue[200]; 
eias See iE 


if (response == GTK_RESPONSE_ACCEPT) 

{ 
artist_const = gtk_entry_get_text (GTK_ENTRY (artist_entry)); 
title_const = gtk_entry_get_text (GTK_ENTRY (title_entry)); 
catalogue_const = gtk_entry_get_text (GTK_ENTRY (catalogue_entry)); 











strepy(artist, artist_const); 
strcpy (title, title_const) ; 
strcpy (catalogue, catalogue_const) ; 


add_cd(artist, title, catalogue, cd_id); 
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addcd_dialog = NULL; 
gtk_widget_destroy (GTK_WIDGET (dialog) ); 





This is the heart of the application: retrieving the search results and populating the GtkTreeView. 


void on_search_button_clicked (GtkButton *button, gpointer userdata) 


{ 


struct cd_search_st cd_res; 
Seructe currenti cdistiecd, 

struct current_tracks_st ct; 

gine resi wesA, ieasiy 

gchar track_title[110]; 

const gchar *search_string_const; 
gchar search_string[200]; 

gchar search_text[200]; 

Gime a = O, 3 = OF 


GtkTreeStore *tree_store; 
GtkTreeIter parent_iter, child_iter; 





memset (&track_title, 0, sizeof(track_title)); 


Here you get the search string from the entry widget, copy into a non-const variable, and fetch 
the matching CD IDs: 


search_string_const = gtk_entry_get_text (GTK_ENTRY (userdata) ) ; 
strcpy (search_string, search_string_const) ; 
resl = find_cds(search_string, &cd_res) ; 


Next you update the appbar to display a message informing the user of the result of the search: 
sprintf (search_text, " Displaying %*d result(s) for search string ' %s '", 


MIN(resl, MAX_CD_RESULT), search_string) ; 
gnome_appbar_push (GNOME_APPBAR( appbar), search_text); 





Now you have the search results and can populate the GtkTreeStore with the results. For each CD 
ID you need to fetch the corresponding current_cd_st struct that contains the title and author of 
the CD and then fetch the list of its tracks. Limit the number of entries to MAX_CD_RESULT defined 
in app_mysq] .h to ensure you don’t overfill the GtkTreeStore. 


OLUMNS, 

TYPE STRING, 
- TYPE STRING, 
- TYPE_STRING) ; 


tree_store = gtk_tree_store_new ( 





QQNn4 








while (i < resl && i < MAX_CD_RESULT) 
{ 





res2 = get_cd(cd_res.cd_id[i], &cd); 


/* Add a new row to the model */ 
gtk_tree_store_append (tree_store, &parent_iter, NULL); 
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gtk_tree_store_set (tree_store, &parent_iter, 
COLUMN_TITLE, cd.title, 
COLUMN_ARTIST, cd.artist_name, 
COLUMN_CATALOGUE, cd.catalogue, -1 
Ng 








res3 = get_cd_tracks(cd_res.cd_id[i++], &ct); 

J = 0; 

/* Populate the tree with the current cd's tracks */ 
while (j < res3) 

{ 


sprintf (track_title, " Track %d. ", j+1); 


r 


strcat (track_title, ct.track[j++]); 
gtk_tree_store_append (tree_store, &child_iter, &parent_iter); 


gtk_tree_store_set (tree_store, &child_iter, 
COLUMN_TITLE, track_title, -1); 


gtk_tree_view_set_model (GTK_TREE_VIEW (treeview), GTK_TREE_MODEL (tree_store)); 





10. The adaca dialog is nonmodal. Therefore, you check to see if it’s already active before creating 
and showing it: 


void on_addcd_activate (GtkMenuItem * menuitem, gpointer user_data) 
{ 
if (addcd_dialog != NULL) 
return; 


addcd_dialog = create_addcd_dialog(); 
gtk_widget_show_all (addcd_dialog) ; 


} 


gboolean close_app ( GtkWidget * window, gpointer data) 
{ 
gboolean exit; 


if ((exit = confirm_exit())) 
{ 

quit_app (NULL, NULL); 
} 


return exit; 


11. When you click the About button, a standard GNOME about box pops up: 


void on_about_activate (GtkMenuItem * menuitem, gpointer user_data) 
{ 
const char * authors[] = {"Wrox Press", NULL}; 
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GtkWidget *about = gnome_about_new ("CD Database", "1.0", 
"(c) Wrox Press", 
"Beginning Linux Programming", 
(const char ** ) authors, NULL, 
"Translators", NULL); 
gtk_widget_show (about) ; 


Try It Out main.c 


Enter the following code as main.c, which contains the main function for the program. 


1. 


After the include statements, you reference username and password entry boxes from 
interface.c: 


#include <stdio.h> 
#include <stdlib.h> 


#include "app_gnome.h" 


extern GtkWidget *username_entry; 
extern GtkWidget *password_entry; 


gint main(gint argc, gchar *argv[]) 


{ 


GtkWidget *main_window; 
GtkWidget *login_dialog; 
const char *user_const; 
const char *pass_const; 
gchar username[100]; 
gchar password[100]; 
gint result; 


Initialize the GNOME libraries as usual, and then create and display the main window and your 
login dialog: 


F: 


gnome_program_init ("CdDatabase", "0.1", LIBGNOMEUI_MODULI 
argc, argv, 
GNOME_PARAM APP DATADIR, "", 
NULL) ; 

main_window = create_main_window() ; 

gtk_widget_show_al1 (main_window) ; 











login_dialog = create_login_dialog(); 


You loop until the user enters a correct username-password combination. The user can quit by 
clicking Cancel, in which case she is then asked to confirm the action. 


while (1) 


{ 
result = gtk_dialog_run (GTK_DIALOG (login_dialog) ); 
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if (result != GTK_RESPONSE_ACCEPT) 
{ 
if (confirm_exit()) 
return 0; 
else 
continue; 
} 
user_const = gtk_entry_get_text (GTK_ENTRY (username_entry) ) ; 
pass_const = gtk_entry_get_text(GTK_ENTRY (password_entry) ); 
strcpy (username, user_const) ; 
strcpy (password, pass_const); 








if (database_start (username, password) == TRUE) 
break; 


4. If database_start fails, you display an error message and the login dialog is shown again: 


GtkWidget * error_dialog = gtk_message_dialog_new (GTK_WINDOW(main_window) , 
GTK_DIALOG_DESTROY_WITH_PARENT, 
GTK_MESSAGE_ERROR, 
GTK_BUTTONS_CLOSE, 
"Could not log on! - Check Username and Password") ; 
gtk_dialog_run (GTK_DIALOG (error_dialog) ); 
gtk_widget_destroy (error_dialog) ; 














gtk_widget_destroy (login_dialog) ; 
gtk_main(); 


return 0; 
5. You'll write a makefile to compile this application. As in Chapter 8, you may need to add the 
location of the mysqlclient library with something like the following: 
-L/usr/1lib/mysql 


Place the directory where your system has the MySQL libraries after the -L. 


all: app 
app: app_mysql.c callbacks.c interface.c main.c app_gnome.h app_mysql.h 
gcc -o app -I/usr/include/mysql app_mysql.c callbacks.c interface.c main.c - 


lmysqlclient ‘pkg-config --cflags --libs libgnome-2.0 libgnomeui-2.0` 


clean: 
rm -£ app 


6. Now just use the make command to compile the CD application: 
make -f Makefile 


When you run app, you should get your CD application — GNOME style (see Figure 16-15)! 
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File Help 
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Add Quit 





Search String: | Pink |Search | 


Title Artist Catalogue 
b Dark Side of the Moon Pink Floyd B000024D4P 
v Wish You Were Here Pink Floyd B000024D4S 
Track 1. Shine on you crazy diamond 
Track 3. Have a cigar 
Track 4. Wish you were here 
Track 5. Shine on you crazy diamond pt.2 








Displaying 2 result(s) for search string * Pink‘ 


Figure 16-15 





Summary 


In this chapter, you’ve learned about programming with the GTK+/GNOME libraries to produce 
professional-looking GUI applications. First, you looked at the X Window System and how toolkits 
fit into the picture and then saw briefly how GTK+ works under the hood with its object system and 
signal/callback mechanism. 


You then moved on to look at the API of GTK+ widgets, showing simple and more advanced examples 
in action in several program listings. In looking at the GnomeApp widget, you learned how to easily create 


menus using helper macros. Finally, you saw how to create modal and nonmodal dialog boxes to interact 
with the user. 


Last, you created a GNOME/GTK+ GUI for your CD database, enabling you to log on to the database, 
search for CDs, and add CDs to the database. 


In Chapter 17, you look at the rival toolkit to GTK+ and learn how to program KDE using Qt. 
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Programming KDE Using Qt 


In Chapter 16, you looked at the GNOME/GTK+ GUI libraries for creating graphical user inter- 
faces under X. These libraries are only half of the story; the other big player on the GUI scene in 
Linux is KDE/Qt, and in this chapter you look at these libraries and see how they shape up 
against the competition. 


Qt is written in C++, the standard language in which to write Qt/KDE applications, so in this 
chapter you'll be obliged to take a diversion from the usual C and get your hands dirty with C++. 
You might like to take this opportunity to refresh your memory on C++, especially reminding 
yourself of the principles of derivation, encapsulation, method overloading, and virtual functions. 


In this chapter, we cover 


An introduction to Qt 
Installing Qt 

Getting started 

Signal/slot mechanism 

Qt widgets 

Dialogs 

Menus and toolbars with KDE 





Cocovovoveoo eo 


Building your CD database application with KDE/Qt 


Introducing KDE and Qt 


KDE (K Desktop Environment) is an open source desktop environment based on the Qt GUI 
library. A host of applications and utilities are part of KDE, including a complete office suite, a 
Web browser, and even a fully featured IDE for programming KDE/(Qt applications (KDevelop, 
covered in Chapter 9). Industry recognition of how advanced KDE’s applications are came when 
Apple chose to use KDE’s Web browser as the core of the primary Web browser for Mac OS X, 
called Safari, known as a very fast browser. 
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The KDE project’s homepage is at http: //www.kde.org, where you can find detailed information, 
download KDE and KDE applications, find documentation, join mailing lists, and get other developer 
information. 


The latest version of KDE at the time of writing is 3.5.7, and because this is the version that ships with 
current Linux distributions, we'll assume you have KDE 3.5 or higher installed. Work progresses on a 
major upgrade called KDE 4.0. You can also download pre-release versions of KDE 4.0. Similarly, the 
latest version of Qt is 4.3 but most Linux distributions have set up a version of Qt 3, such as 3.3, as 
the default Qt version. This chapter covers Qt 3.3, because it is most commonly available. 


From a programmer’s perspective, KDE offers dozens of KDE widgets, usually derived from their Qt 
counterparts to provide enhancements and greater ease of use. KDE widgets offer greater integration 
with the KDE desktop than you get with Qt alone; for example, you get session management. 


Qt is a mature, cross-platform GUI toolkit written in C++. Qt is the brainchild of Trolltech, a Norwegian 
company that develops, markets, and supports Ot and Qt-related software for the commercial market. 
Trolltech loudly touts the cross-platform capabilities of Qt, which is undeniably impressive; Qt has 
native support on Linux and UNIX derivatives, Windows, Mac OS X, and even embedded platforms, 
which gives Qt a great competitive advantage over its rivals. 


A specialized version of Qt runs on cell phones. Another version runs on the Sharp Zaurus PDA and 
similar platform. Qt Jambi provides a Java version of the toolkit. 


Trolltech currently sells the commercial versions of Qt at a prohibitively high price for the casual user 
or hobbyist. Fortunately, Trolltech realizes the value in offering a zero-price version to the free software 
community, and therefore it offers a free version, Qt Open Source Edition for Linux, Windows, and Mac 
OS X. In return for a free version of Qt, Trolltech gets a large user install base, a large programmer com- 
munity, and a high profile for its product. 


Qt Open Source Edition is licensed under the GPL, which means you can program using the Qt libraries 
and distribute your own GPL software free of charge. As far as we can tell, the two main differences 
between the Open Source and the professional versions are the lack of support and the fact that you 
can’t use Qt software in commercial applications. Trolltech’s website at http: //www.trolltech.com 
has all the API documentation that you need. 


Installing Qt 


Unless you have a particular reason to compile from source, it’s easiest to find a binary package or RPM 
for your distribution. Fedora Linux 7 ships with qt-3 .3 .8-4.1386.xrpm, which you can install using 
the following command: 


$ rpm -Uvh qt-3.3.8-4.1386.rpm 


You can also install Qt and the KDE programming libraries with the Package Manager application (see 
Figure 17-1). 
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Figure 17-1 


If you do want to download the source code and build Qt yourself, you can get the latest source from the 
Trolltech FTP site at ftp: //ftp.trolltech.com/qt/source/. The source package comes with exten- 
sive instructions on how to compile and install Qt in the INSTALL file in the tarred package: 

$ cd /usr/local 

$ tar -xvzf qt-x11-free-3.3.8.tar.gz 

$ ./configure 

$ make 
You'll also need to add a line to /etc/1d.so.conf: 

/usr/1lib/qt-3.3/lib 


You can add this line anywhere in the file. 


On Fedora and Red Hat Linux systems, the line should be stored in /etc/1d.so.conf£.d/ 
qt-i386.conf. If you have installed Qt as shown in Figure 17-1, this step will already be done. 


When Qt is properly installed, the QTDIR environment variable should be set to the Qt installation direc- 
tory. You can check that this is the case as follows: 


$ echo $QTDIR 
/usr/lib/qt-3.3 


Also make sure the 1ib directory is added to /etc/1d.so.conf. 
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Then run the following command as superuser: 
# ldconfig 


Try out the simplest Qt program and make sure your installation is working properly. 


Try It Out QMainWindow 


Type (or copy and paste from the code downloads) this program and call it qt1. cpp: 


#include <qapplication.h> 
#include <qmainwindow.h> 


int main(int argc, char **argv) 

{ 
QApplication app (argc, argv); 
QMainWindow *window = new QMainWindow() ; 
app.setMainWidget (window) ; 


window->show() ; 


return app.exec(); 


} 
To compile, you'll need to include the Qt include and 1ib directories: 

$ g++ -o qt1 qt1l.cpp -IS$QTDIR/include -L$QTDIR/1lib -lqui 

On some platforms, the library at the end will be -1qt. With Qt 3.3, though, use -1qui. 
When you run the application, you should get a Qt window (see Figure 17-2). 


$ ./qt1 


TAR 








Figure 17-2 


How It Works 


Unlike GTK+, there’s no all-encompassing qt .h header file, so you must explicitly include header files 
for each object you use. 


The first object you encounter is QApplication. This is the main Qt object you must construct, passing 
in the command-line arguments before you begin. Each Qt application must have one and only one 
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QApplication object that you must create before doing anything else. QApplication deals with under- 
the-hood Qt operations such as event handling, string localization, and controlling the look and feel. 


There are two QApplication methods you'll use: setMainWidget, which sets the main widget of 
your application, and exec, which starts the event loop running. exec doesn’t return until either 
QApplication::quit() is called or the main widget is closed. 


QMainWindow is the Qt base window widget that has support for menus, a toolbar, and a status bar. It’s 
featured a great deal in this chapter as you learn how to extend it and add widgets to create an interface. 


Next we introduce the mechanism of event-driven programming, and you'll add a PushButton widget 
to the application. 


Signals and Slots 


As you saw in Chapter 16, signals and signal handling are the primary mechanisms a GUI application 
uses to respond to user input and are central features of all GUI libraries. Qt’s signal-handling mecha- 
nism consists of signals and slots, which are Qt’s names for signals and callback functions in GTK+ or 
Java events and event handlers. 


Note that a Qt signal is quite separate from a UNIX signal, as discussed in Chapter 11. 


Here’s a reminder of how event-driven programming works: A GUI consists of menus, toolbars, buttons, 
entry boxes, and many other GUI elements that are collectively known as widgets. When the user inter- 
acts with a widget, for example activating a menu item or entering some text in an entry box, the widget 
will emit a named signal such as clicked, text_changed, or key_pressed. You'll usually want to do 
something in response to the user’s action, such as save a document or quit the application, and you 

do this by connecting a signal to a callback function or, in Qt parlance, a slot. 


Using signals and slots in Qt is rather special — Qt defines two new aptly named pseudo-keywords, 
signals and slots, to identify in your code the signals and slots of the class. This is great for readabil- 
ity and code maintenance, but it means you must pass your code through a separate pre-preprocessing 
stage to search and replace these pseudo-keywords with additional C++ code. 


Qt code, therefore, is not true C++ code. This has sometimes been an issue for some developers. See 
http: //doc.trolltech.com/ for Qt documentation, including reasons for these new pseudo C++ 
keywords. Furthermore, the use of signals and slots does not differ all that much from the Microsoft 
Foundation Classes, or MFC, on Windows, which also uses a modified definition of the C++ language. 


There are some restrictions to how signals and slots can be used in Qt, but these are not significantly 





limiting: 
Q Signals and slots must be member functions of a class derived from QObject. 
Q = If using multiple inheritance, Q0bject must appear first in the class list. 
Q AQ_OBJECT statement must appear in the class declaration. 
Q Signals cannot be used in templates. 
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Q Function pointers cannot be used as arguments to signals and slots. 





Q Signals and slots cannot be overridden and upgraded to public status. 


Because you need to write your signals and slots in a descendant of QObject, it is logical to create your 
interface by extending and customizing a widget, since QWidget, the base Qt widget, is derived from 
QObject. In Qt, you'll nearly always create interfaces by extending widgets such as QMainWindow. 


A typical class definition MyWindow.h for your GUI will look something like this: 


class MyWindow : public QMainWindow 
if 
O OBJECT 
public: 
MyWindow() ; 
virtual ~MyWindow() ; 





signals: 
void aSignal(); 


private slots: 


void doSomething() ; 


Your class derives from QMainWindow, which provides functionality for the main window in the applica- 
tion. Similarly, you'll subclass QDialog when you want a dialog box. First is the Q_OBJECT statement 
that acts as a marker for the preprocessor, followed by the usual constructor and destructor prototypes. 
Next are the signal and slot definitions. 


You have one signal and one slot, both with no arguments. To emit aSignal (), all you need to do is call 
emit somewhere in your code: 


emit aSignal() ; 
That’s it — everything else is handled by Qt. You don’t even need an aSignal () implementation. 


To use slots, you must connect them to a signal. You do this with the appropriately named static connect 
method in the QObject class: 


bool QObject::connect (const QObject * sender, const char * signal, 
const QObject * receiver, const char * member) 


Simply pass in the object that owns the signal (the sender), the signal function, the object that owns the 
slot (the receiver), and finally the name of the slot. 


In the MyWindow example, if you wanted to connect the clicked signal of a QPushButton widget to 
your doSomething slot, you’d write 


connect (button, SIGNAL(clicked()), this, SLOT(doSomething())); 
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Note that you must use SIGNAL and SLOT macros to surround the signal and slot functions. Just as in 
GTK+, you can connect any number of slots to a given signal and also connect a slot to any number of 
signals by multiple connect calls. If connect fails for any reason, it returns FALSE. 


All that remains is to implement your slot, and this takes the form of an ordinary member function: 


void MyWindow: :doSomething () 
{ 
// Slot code 


} 


Try It Out Signals and Slots 


Now that you’ve seen the principles of signals and slots, let’s put this to use with an example. Extend 
QMainWindow and add a button, and connect the button’s clicked signal to a slot. 


1. Enter this class declaration, and call it But tonWindow-h: 


#include <qmainwindow.h> 


class ButtonWindow : public QMainWindow 


{ 
Q_OBJECT 


public: 
ButtonWindow(QWidget *parent = 0, const char *name = 0); 
virtual ~ButtonWindow() ; 


private slots: 
void Clicked() ; 


}; 
2. Nextis the class implementation, But tonWindow. cpp: 


#include "ButtonWindow.moc" 
#include <qpushbutton.h> 
#include <qapplication.h> 
#include <iostream> 


3. Inthe constructor, you set the window title, create the button, and connect the button’s clicked sig- 
nal to your slot. setCaption is a QMainWindow method that unsurprisingly sets the window title. 


ButtonWindow: :ButtonWindow(QWidget *parent, const char *name) 
: QMainWindow(parent, name) 
{ 
this->setCaption("This is the window Title"); 
QPushButton *button = new QPushButton ("Click Me!", this, "Buttonl"); 
button->setGeometry(50,30,70,20); 
connect (button, SIGNAL(clicked()), this, SLOT(Clicked())); 


707 


Chapter 17: Programming KDE Using Qt 


4. Qt manages the destruction of widgets automatically, so your destructor is empty: 
ButtonWindow: : ~ButtonWindow () 
{ 
} 
5. Next, the slot implementation: 
void ButtonWindow: :Clicked (void) 
{ 
std::cout << "clicked!\n"; 


} 


6. Finally, in main you just create an instance of But tonWindow, set it as your application’s main 
window, and show the window onscreen: 


int main(int argc, char **argv) 
{ 
QApplication app(argc, argv) ; 


ButtonWindow *window = new ButtonWindow(); 


app.setMainWidget (window) ; 
window->show() ; 


return app.exec(); 
T. Before you can compile this example, you need to run the preprocessor on the header file. This 
preprocessor program is called the Meta Object Compiler (moc) and should be present in the 
Qt package. Run moc on But tonWindow.h, saving the output as But tonWindow.moc: 
$ moc ButtonWindow.h -o ButtonWindow.moc 
Now you can compile as usual, linking in the moc output: 


$ g++ -o button ButtonWindow.cpp -I$QTDIR/include -L$QTDIR/lib -lqui 


When you run the program, you get the example shown in Figure 17-3. 


How It Works 


We've introduced a new widget and some new functions here, so let’s take a look at these. QPushBut ton 
is a simple button widget that can hold a label and bitmap graphic and can be activated by the user 
clicking with the mouse or using the keyboard. 

The constructor of QPushButton used is quite simple: 


QPushButton: :QPushButton(const QString &text, QWidget *parent, const char* name=0 ) 


The first argument is the text of the button label, then the parent widget, and last the name of the button 
used internally by Qt. 
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B ericfjQ@kayak:/home?2/ericfj/writing/Beginning Linux Programming 4th Ed/c|_)/0) x 
File Edit View Terminal Tabs Help 

[ericfj@kayak chap17 src]$ ./button [A 
clicked! 
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T This is the window Title |-|o|/x | 
Click Me! 

Figure 17-3 


The parent parameter is common to all QWidgets, and the parent widget controls when it is displayed 
and destroyed, and various other characteristics. Passing NULL as the parent argument denotes that 
the widget is top-level and creates a blank window to contain it. In the example you pass the current 
But tonWindow object using this, which adds the button to the But tonWindow main area. 


The name argument sets the name of the widget for use internally by Qt. If Qt encounters an error, the 
widget name will be printed in the error message, so it’s a good idea to choose the appropriate widget 
name, because it’s a great timesaver when debugging. 


You might have noticed that the code rather crudely added the QPushButton to the But tonWindow by 
using the parent parameter of the QPushButton constructor, without specifying the positioning, size, 
border, or anything like that. If you want precise control over widget layout, which is critical in creating 
an attractive interface, you must use Qt’s layout objects. Let’s take a look at these now. 


There are a number of ways to arrange the positioning and layout of widgets in Qt. You’ve already seen 
using absolute coordinates by calling setGeometry, but this is rarely used, because the widgets don’t 


scale and adjust to fit the window if it is resized. 


The preferred method of arranging widgets is by using the QLayout classes or box widgets, which intel- 
ligently resize, after you’ve given them hints on margins and spacing between widgets. 


The key difference between the QLayout classes and box widgets is that layout objects are not widgets. 


The layout classes derive from QObject and not Qwidget, so you are constrained in how you can use 
them. You cannot, for instance, make a QVBoxLayout a central widget of a QMainWindow. 


Box widgets (such as QHBox and QVBox), by contrast, are derived from Qwidget, and therefore you can 


treat them as ordinary widgets. You might well wonder why Qt has both QLayouts and QBox widgets 
with duplicate functionality. Actually QBox widgets are just for convenience, and in essence wrap a 
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QLayout within a QWidget. QLayouts have the advantage of automatically resizing, whereas widgets 
must be manually resized by calling QWidget : :resizeEvent (). 


The QLayout subclasses QVBoxLayout and QHBoxLayout are the most popular way of creating an inter- 
face, and the ones you will most often see in Qt code. 


QVBoxLayout and QHBoxLayout are invisible container objects that hold other widgets and layouts in 
a vertical and a horizontal orientation, respectively. You can create arbitrarily complex arrangements of 
widgets because you can nest layouts by placing a horizontal layout as an element inside a vertical lay- 
out, for example. 


There are three QVBoxLayout constructors of interest (QHBoxLayout has an identical API): 
QVBoxLayout::QVBoxLayout (QWidget *parent, int margin, int spacing, const char 
*name) 
QVBoxLayout::QVBoxLayout (QLayout *parentLayout, int spacing, const char * name) 


QVBoxLayout::QVBoxLayout (int spacing, const char *name) 


The parent of the QLayout can be either a widget or another QLayout. If you specify no parent, you can 
only add the layout to another QLayout later, using the addLayout method. 


margin and spacing set the empty space in pixels placed around the outside of the Qhayout and in 
between individual widgets. 


Once you've created your QLayout, you add child widgets or layouts using a couple of methods: 


QBoxLayout::addWidget (QWidget *widget, int stretch = 0, int alignment = 0 ) 
QBoxLayout::addLayout (QLayout *layout, int stretch 0) 


Try It Out Using QBoxLayout Classes 


In this example, you see the QBoxLayout classes in action by arranging QLabel widgets ina 
QMainWindow. 


1. First, enter the header file, LayoutWindow.h: 
#include <qmainwindow.h> 
class LayoutWindow : public QMainWindow 


{ 
Q_OBJECT 





public: 
LayoutWindow(QWidget *parent = 0, const char *name = 0); 
virtual ~LayoutWindow() ; 
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2. Now enter the implementation, LayoutWindow. cpp: 


#include <qapplication.h> 
#include <qlabel.h> 
#include <qlayout.h> 


#include "LayoutWindow.moc" 


LayoutWindow: :LayoutWindow(QWidget *parent, const char *name) : QMainWindow(parent, name) 
{ 


this->setCaption("Layouts") ; 


3. You need to create a dummy QWidget to hold your QHBoxLayout because you cannot add a 
QLayout directly to a QMainWindow: 


QWidget *widget = new QWidget (this); 
setCentralWidget (widget) ; 


QHBoxLayout *horizontal = new QHBoxLayout (widget, 5, 10, "horizontal"); 
QVBoxLayout *vertical = new QVBoxLayout() ; 


QLabel* labell = new QLabel("Top", widget, "textLabell" ); 
QLabel* label2 new QLabel("Bottom", widget, "textLabel2"); 
QLabel* label3 new Qlabel("Right", widget, "textLabel3"); 





vertical->addWidget (label11) ; 
vertical->addWidget (label2) ; 
horizontal->addLayout (vertical) ; 
horizontal->addWidget (label13) ; 
regstaal LO MOO y 

} 


LayoutWindow: :~LayoutWindow () 
{ 
} 
int main(int argc, char **argv) 
{ 
QApplication app (argc,argv); 
LayoutWindow *window = new LayoutWindow() ; 


app.setMainWidget (window) ; 
window->show() ; 


return app.exec(); 


As before, you need to run moc on the header file before compiling: 


$ moc LayoutWindow.h -o LayoutWindow.moc 
$ g++ -o layout LayoutWindow.cpp -ISQTDIR/include -L$QTDIR/1lib -lqui 


When you run this program, you get your arrangement of QLabels (see Figure 17-4). Try resizing the 
window and see how the labels expand and shrink to fit the available space. 
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@ Layouts DO * 





Figure 17-4 


How It Works 


The LayoutWindow. cpp code creates two box layout widgets for laying out widgets, both a horizontal 
and a vertical box layout. The vertical layout gets two labels, described appropriately enough, as Top and 
Bottom. The horizontal box layout also holds two widgets, a label shown as Right, as well as the vertical 
box layout. You can freely place layout widgets inside of layout widgets as shown in this example. 


Try changing the code in LayoutWindow. cpp to experiment and better see how the box layouts work. 


We've covered the basic principles of using Qt — signals and slots, moc, and layouts — so it’s time to 
investigate the widgets more closely. 





Qt Widgets 


There are widgets for every occasion in Qt, and looking at them all would take up the rest of the book. 
In this section you take a look at the common Qt widgets, including data entry widgets, buttons, combo 
box, and list widgets. 


QLineEdit 


QLineEdit is Qt’s single-line text entry widget. Use it for inputting brief amounts of text, such as a user’s 
first name. With a QLineEdit widget, you can limit text input using an input mask to fit a template or, for 
the ultimate control, you can apply a validator function, for example, to ensure the user enters a proper 
date, phone number, or other similar value. QLineEdit has editing features, enabling you to select parts 
of the text, cut and paste, undo, redo, and the like from both a user’s perspective and using the API. 


The constructors and most useful methods are 


#include <qlineedit.h> 


QLineEdit::QlineEdit (QWidget *parent, const char* name = 0 ) 
QLineEdit::QLineEdit (const QString &contents, QWidget *parent, 
const char *name = 0 ) 
QLineEdit::QLineEdit (const QString &contents, const QString &inputMask, 
QWidget *parent, const char *name = 0 ) 


void setInputMask (const QString &inputMask) 
void insert (const QString &newText ) 

bool isModified (void) 

void setMaxLength (int length) 


void setReadOnly (bool read) 
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void setText (const QString &text) 
QString text (void) 
void setEchoMode (EchoMode mode) 


In the constructors, you set the parent widget and widget name as usual with parent and name. 
An interesting property is EchoMode, which determines how the text appears in the widget. 


It can take one of three values: 





Qo QbineEdit: :Normal: Display inputted characters (default) 
Qo QbineEdit: : Password: Display asterisks in place of characters 
Qh QLineEdit: :NoEcho: Display nothing 





Set the mode using the setEchoMode: 


lineEdit->setEchoMode (QLineEdit: : Password); 





An enhancement introduced in Qt 3.2 is inputMask, which restricts input according to the mask rule. 


inputMask is a string made up of characters, each of which corresponds to a rule that accepts a certain 
range of characters. If you’re familiar with regular expressions, inputMask uses much the same principle. 


There are two sorts of inputMask characters: those that denote a certain character must be present, and 
those that, if a character is present, restrict it to fall under the rule. The following table shows examples 
of these characters and their meanings. 


Required Character Characters That Are Meaning 
Permitted But Not Required 

A a ASCII A-Z, a-z 

N n ASCII A-Z, a-z, 0-9 

X x Any character 

9 0 Numeric 0-9 

D d Numeric 1-9 


Our inputMask is a string made up from a combination of these characters, optionally terminated by a 
semicolon. There are further special characters that also have meaning as shown in the following table. 


Character Meaning 
# Plus/minus permitted but not required. 
> Converts following input to uppercase. 


Continued on next page 
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Character Meaning 
< Converts following input to lowercase. 
! Stops converting case. 


\ Escape character to use special characters as separators. 





All other characters in the inputMask act as separators in the QLineEdit. 


The following table shows some examples of masks and their allowed input. 


Example Allowed Input 

"AAAAAA-999D" Allows Athens-2004 but not Sydney-2000 or Atlanta-1996. 
"AAAAnn-99-99;" Allows March-03-12 but not May-03-12 or September-03-12. 
"000.000.000.000" Allows IP address, for example, 192.168.0.1. 


Try It Out QLineEdit 


Now see QLineEdit in action. 


1. First, the header file, LineEdit .h: 





#include <qmainwindow.h> 
#include <qlineedit.h> 
#include <qstring.h> 


class LineEdit : public QMainWindow 


{ 
Q_OBJECT 





public: 
LineEdit (QWidget *parent = 0, const char *name = 0); 
QLineEdit *password_entry; 


private slots: 
void Clicked(); 
hi 


2. tLineEdit.cpp is the now-familiar class implementation file: 


#include "LineEdit.moc" 
#include <qpushbutton.h> 
#include <qapplication.h> 
#include <qlabel.h> 
#include <qlayout.h> 
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#include <iostream> 


LineEdit::LineEdit (QWidget *parent, const char *name) : QMainWindow(parent, name) 


{ 
QWidget *widget = new QWidget (this); 
setCentralWidget (widget) ; 


3. Use a QGridLayout to arrange the widgets. Specify the number of rows and columns, the mar- 


gin settings, and the spacing: 
QGridLayout *grid = new QGridLayout (widget,3,2,10, 10,"grid"); 
QLineEdit *username_entry = new QLineEdit( widget, "username_entry") ; 


password_entry = new QLineEdit( widget, "password_entry") ; 
password_entry->setEchoMode (QLineEdit: : Password) ; 





grid->addWidget (new QLabel("Username", widget, "userlabel"), 0, 0, 0); 
grid->addWidget (new QLabel("Password", widget, "passwordlabel"), 1, 0, 


grid->addwWidge 
grid->addwWidge 


t(username_entry, 0,1, 0); 

t(password_entry, 1,1, 0); 

QPushButton *button = new QPushButton ("Ok", widget, "button"); 
grid->addWidget (button, 2,1,Qt::AlignRight) ; 





ies 350, All) }) 7 





connect (button, SIGNAL(clicked()), this, SLOT(Clicked())); 
J 
void LineEdit::Clicked (void) 
{ 
std::cout << password_entry->text() << "\n"; 
} 


int main(int argc, char **argv) 

{ 
QApplication app (argc,argv); 
LineEdit *window = new LineEdit(); 





app.setMainWidget (window) ; 
window->show() ; 


return app.exec(); 


When you run this program, you should get the example shown in Figure 17-5. 


How It Works 





You’ve created two QLineEdit widgets, made one a password entry by setting the EchoMode, and set it 
to print its contents when you click the PushButton. Note the introduction of the QGridLayout widget, 
which is very useful for laying out widgets in a grid pattern. When you add a widget to the grid, you 


pass the row and column number, starting at 0, 0 for the top-left cell. 
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a ericfj@kayak:/home2/erictj/writing/Beginning Linux Programming 4th Ed/c -N| x j 
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Password +eseeses | 





Ok 


























Figure 17-5 


Qt Buttons 


Button widgets are ubiquitous widgets, and they vary little in appearance, usage, and API from toolkit 
to toolkit. It’s no surprise that Ot offers standard PushButton, CheckBox, and RadioButton variants. 


QButton: The Button Base Class 


Button widgets in Qt all derive from the abstract QBut ton class. This class has methods to query and 
toggle the on/off state of the button and to set the button’s text or pixmap. 


You should never need to instantiate a QButton widget itself (don’t get confused between a QBut ton and 
QPushButton!), so you needn’t show the constructors; however, here are the useful member functions: 


#include <qbutton.h> 


virtual void QButton::setText ( const QString & ) 
virtual void QButton::setPixmap ( const QPixmap & ) 
bool QButton::isToggleButton () const 

virtual void QButton::setDown ( bool ) 

bool QButton::isDown () const 

bool QButton::isOn () const 

enum QButton::ToggleState { Off, NoChange, On } 
ToggleState QButton::state () const 


The isDown and isOn functions are identical in meaning. They both return TRUE if the button is pressed 
or activated. 


Often, you'll want to disable or gray out an option if it isn’t currently available. You can disable any 
widget including QBut tons by calling QWidget: :setEnable (FALSE). 
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There are three subclasses of QBut ton of interest here: 


Q QPushButton: A simple button widget that performs some action when clicked 
Qo = QCheckBox: A button widget that can toggle between on and off states to indicate some option 


Qh = QRadioButton: A button widget normally used in groups where only one button can be active 
in a group at a time 


QPushButton 


QPushBut ton is the standard generic button that contains text such as “OK” or “Cancel” and/or a 
pixmap icon. Like all QBut tons, it emits the clicked signal when it’s activated, and is usually used to 
connect a slot and perform some action. 


You’ve already used QPushButton in your examples, and there’s really only one other thing of interest 
to say about this simplest of Qt widgets. QPushBut ton can be switched from a stateless button into a 
toggle button (that is, can be turned on or off) by calling set ToggleButton. (If you recall from the pre- 
ceding chapter, GTK+ has separate widgets for the purpose.) 


For completeness, here are the constructors and useful methods: 


#include <qpushbutton.h> 


QPushButton (QWidget *parent, const char *name = 0) 
QPushButton (const QString &text, QWidget *parent, const char *name = 0) 
QPushButton (const QIconSet &icon, const QString &text, 

QWidget *parent, const char * name = 0 ) 


void QPushButton::setToggleButton (bool); 


QCheckBox 


QCheckBox is a button that has state; that is, it can be turned on or off. The appearance of QCheckBox 
depends on the current windowing style (Motif, Windows, and so on) but is usually drawn as a ticked 
box with text to the right. 


You can also set QCheckBox to be a third, in-between state that indicates “no change.” This is useful on 
the rare occasions when you can’t read the state of the option the QCheckBox represents (and therefore 
set the QCheckBox on or off yourself), but still want to give the user a chance to leave it unchanged as 
well as actively set it on or off. 


#include <qcheckbox.h> 


QCheckBox (QWidget *parent, const char *name = 0 ) 
QCheckBox (const QString &text, QWidget *parent, const char *name = 0 ) 


bool QCheckBox::isChecked () 


void QCheckBox::setTristate ( bool y = TRUE ) 
bool QCheckBox::isTristate () 
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QRadioButton 


Radio buttons are toggle buttons used to represent exclusive choices when you can select only one option 
out of a group of options presented (think back to those old car radios, where only one station button could 
be pressed in at a time). QRadioButtons themselves are hardly any different from QCheckBoxes, because 
the grouping and exclusivity are all handled by the QBut tonGroup class, the main difference being that 
radio buttons appear as round buttons rather than ticked boxes. 


QButtonGroup is a widget that makes handling groups of buttons easier by providing convenience 
methods: 


#include <qbuttongroup.h> 


QButtonGroup (QWidget *parent = 0, const char * name = 0 ) 
QButtonGroup (const QString & title, QWidget * parent = 0, const char * name = 0 ) 


int insert (QButton *button, int id = -1) 
void remove (QButton *button) 
int id (QButton *button) const 


int count () const 
int selectedId () const 


Using a QButtonGroup couldn’t be simpler; it even offers an optional frame around the buttons if you 
use the title constructor. 


You can add a button to a QButtonGroup using either insert or by specifying the QButtonGroup as 
the parent widget of the button. You can specify an id with insert to uniquely identify each button in 
the group. This is especially useful when querying which button is selected, because selectedId 
returns the id of the selected button. 


All QRadioButtons you add to the group are automatically set to be exclusive. 
The QRadioButton constructors and one unique method shouldn’t be too surprising: 


#include <qradiobutton.h> 


QRadioButton (QWidget *parent, const char *name = 0 ) 
QRadioButton (const QString &text, QWidget *parent, const char *name = 0 ) 


bool QRadioButton::isChecked () 


Try It Out QButtons 


Now put this knowledge to some use, with a Qt buttons example. The following program creates different 
types of buttons (radio, checkbox, and pushbuttons) to show how to use these widgets in your applications. 


1. Enter Buttons.h: 


#include <qmainwindow.h> 
#include <qcheckbox.h> 
#include <qbutton.h> 
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#include <qradiobutton.h> 


class Buttons : public QMainWindow 


{ 


yy 


3. 


Q OBJECT 

public: 
Buttons (QWidget *parent = 0, const char *name = 0); 
You'll query the state of your buttons later in the slot function, so declare the button pointers as 
private in the class definition, as well as a helper function PrintActive: 

private: 


void PrintActive(QButton *button) ; 
QCheckBox *checkbox; 
QRadioButton *radiobuttonl, *radiobutton2; 


private slots: 
void Clicked(); 


Here’s Buttons. cpp: 


#include "Buttons.moc" 
#include <qbuttongroup.h> 


#include <qpushbutton.h> 


#include <qapplication.h> 
#include <qlabel .h> 
#include <qlayout.h> 


#include <iostream> 


Buttons: :Buttons(QWidget *parent, const char *name) : QMainWindow(parent, name) 


{ 


QWidget *widget = new QWidget (this); 
setCentralWidget (widget) ; 


QVBoxLayout *vbox = new QVBoxLayout (widget,5, 10,"vbox"); 


checkbox = new QCheckBox("CheckButton", widget, "check") ; 
vbox->addwWidget (checkbox) ; 


Here you create a QButtonGroup for your two radio buttons: 


QButtonGroup *buttongroup = new QButtonGroup (0) ; 
radiobuttonl = new QRadioButton("RadioButtonl", widget, "radiol"); 


buttongroup->insert (radiobutton1) ; 
vbox->addWidget (radiobutton1) ; 


719 


Chapter 17: Programming KDE Using Qt 


radiobutton2 = 
buttongroup->insert (radiobutton2) ; 
vbox->addWidget (radiobutton2) ; 


QPushButton *button = 
vbox->addWidget (button) ; 
meSayz els 5 0h mez Ome. 


connect 


new QRadioButton("RadioButton2", widget, 


new QPushButton ("Ok", widget, 


(button, SIGNAL(clicked()), 


eevee" )} p 


Moybhercroyat!” }) 


this, SLOT(Clicked())); 


5. Next is a convenience method for printing the state of the given QButton: 


void Buttons::PrintActive(QButton *button) 


{ 


if (button->isOn()) 

std::cout << button->name() << " 
else 

std::cout << button->name() << " 


} 


void Buttons: :Clicked(void) 

{ 
PrintActive (checkbox) ; 
PrintActive(radiobutton1) ; 
PrintActive(radiobutton2) ; 
Siecls scours << NT > 

} 


int main(int argc, 
{ 
QApplication app(argc, argv) ; 
Buttons *window = new Buttons (); 


char **argv) 


app.setMainWidget (window) ; 
window->show() ; 


return app.exec(); 


How It Works 


This simple example shows how to query various Qt button widget types. As you can see, these widgets 
all work the same once created, for the most part. For example, the PrintActive function shows how 
to get the state of a button, on or of £. Notice how this works for all the state-maintaining button types, 
such as the checkbox and radio buttons. For the most part, just the calls to create a button widget differ. 
And, radio buttons, being the most complex (because only one in a group can be on), require the most 
work to create. For radio buttons, you need to create a QBut tonGroup to ensure that only one radio but- 


ton in the group can be active at any time. 


is checked\n"; 


is not checked\n"; 
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QComboBox 


Radio buttons are an excellent way of enabling the user to select from a small number of options, say 

six or fewer. When you have more than six, things start to get out of hand and it becomes increasingly so 
as the number of options increases to keep the window to a sensible size. A perfect solution is to use an 
entry box with drop-down menu, also known as a combo box. The options appear when you click and 
reveal the menu, and the number of options is limited only by how practical it becomes to search 
through the list. 


QComboBox combines the functionality of a QLineEdit, QPushButton, and drop-down menus, enabling 
the user to pick a single option from an unlimited choice of options. 


A QComboBox can be either read/write or read-only. If it is read/write the user can type an alternative to 
the options offered; otherwise the user is limited to selecting from the drop-down list. 


When you create a QComboBox, you can specify whether it’s read/write or read-only as a boolean in the 
constructor: 


QComboBox *combo = new QComboBox(TRUE, parent, "widgetname") ; 


Passing TRUE sets the QComboBox to Read/Write mode. The other parameters are the usual parent 
widget pointer and widget name. 


Like all Qt widgets, QComboBox is flexible in the way you can use it and it offers a good deal of functionality. 
You can add options individually or as a set, either as QStrings or using the traditional char* format. 


To insert a single item, call insert Item: 
combo->insertItem(QString("An Item"), 1); 


This takes a QString object and a position index. Here, the value of 1 sets the item to be first in the list. 
To add it to the end, just pass any negative integer. 


More commonly you'll add several items at a time, and for this you can use the QStrList class, or, as 
here, a char* array: 


char* weather[] = {"Thunder", "Lightning", "Rain", 0}; 
combo->insertStrList (weather, 3); 


Again, you can specify an index for the inserted items in the list. 
If the QComboBox is read/write, values that the user types in can be automatically added to the list of 
options. This is a useful time-saving feature that saves the user from repeated typing if he or she wants 


to select the same typed-in value more than once. 


InsertionPolicy controls where the new entry is added in the option list. You can pick from one of the 
options shown in the following table. 
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Options What It Does 

QComboBox: :AtTop Inserts the new entry as the first option in the list. 
QComboBox: :AtBottom Inserts the new entry as the last option. 

QComboBox: :AtCurrent Replaces the previously selected option. 

QComboBox: : BeforeCurrent Inserts the entry before the previously selected option. 
QComboBox: :AfterCurrent Inserts the entry after the previously selected option. 
QComboBox: :NoInsertion New entry is not inserted into option list. 


To set the policy, call the setInsertionPolicy method on the QComboBox: 
combo->setInsertionPolicy (QComboBox: :AtTop) ; 

Let’s take a peek at the constructors and a selection of the QComboBox methods: 
#include <qcombobox.h> 


QComboBox (QWidget *parent = 0, const char *name = 0) 
QComboBox (bool readwrite, QWidget *parent = 0, const char *name = 0) 


int count () 

void insertStringList (const QStringList &list, int index = -1) 

void insertStrList (const QStrList &list, int index = -1) 

void insertStrList (const QStrList *list, int index = -1) 

void insertStrList (const char **strings, int numStrings = -1, int index = -1) 
void insertItem (const QString &t, int index = -1) 

void removeItem (int index) 


virtual void setCurrentItem (int index) 
QString currentText () 

virtual void setCurrentText (const QString &) 
void setEditable (bool) 


The function count returns the number of options in the list. QStringList and QStrList are Qt string 
collection classes you can use to add options. You can remove options using removeItem, get and set 


the current option using currentText and setCurrentText, and toggle the editable state using 
setEditable. 





QComboBox emits the textChanged (QStringé&) signal whenever a new option is selected, passing the 


newly selected option as an argument. 


Try It Out QComboBox 


In this example you have a go at using QComboBox, and see how signals and slots with parameters work 
in action. You’ll create a ComboBox class that inherits QMainWindow. It’ll have two QComboBoxes, one 
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read/write and one read-only, and you'll connect to the textChanged signal to get the currently 
selected value each time it changes. 


1. Enter the following and name the file ComboBox .h: 


#include <qmainwindow.h> 
#include <qcombobox.h> 


class ComboBox : public QMainWindow 
{ 
Q OBJECT 


public: 
ComboBox(QWidget *parent = 0, const char *name = 0); 


private slots: 
void Changed(const QString& s); 
Ig 


2. The interface consists of two QComboBox widgets, one editable and the other read-only. You 
populate both widgets with the same list of items: 


#include "ComboBox.moc" 


#include <qlayout.h> 
#include <iostream> 


ComboBox: : ComboBox (QWidget *parent, const char *name) : QMainWindow(parent, name) 


{ 
QWidget *widget = new QWidget (this) ; 
setCentralWidget (widget) ; 


QVBoxLayout *vbox = new QVBoxLayout (widget, 5, 10,"vbox"); 





QComboBox *editablecombo = new QComboBox(TRUE, widget, "editable"); 
vbox->addWidget (editablecombo) ; 
QComboBox *readonlycombo = new QComboBox(FALSE, widget, "readonly") ; 
vbox->addWidget (readonlycombo) ; 


static const char* items[] = { "Macbeth", "Twelfth Night", "Othello", 0 }; 
editablecombo->insertStrList (items); 
readonlycombo->insertStrList (items); 





connect (editablecombo, SIGNAL (textChanged(const QStringé&)), 
this, SLOT(Changed(const QString&))); 
resize( 350, 200 ); 


3. This is the slot function. Note the QString parameter s that’s passed by the signal: 


void ComboBox: :Changed(const QString& s) 
{ 


Sikclsscomc @< 6 << Tins 


723 


Chapter 17: Programming KDE Using Qt 


int main(int argc, char **argv) 

{ 
QApplication app(argc, argv) ; 
ComboBox *window = new ComboBox() ; 


app.setMainWidget (window) ; 
window->show() ; 


return app.exec(); 


} 


You can see the newly selected options from the editable QComboBox printed out on the command line in 
Figure 17-6. 














a ericfj@kayak:/home2/ericfj/writing/Beginning Linux Programming 4th Ed/¢|—|/m)|x ] 
file Edit View Terminal Tabs Help 


[ericfj@kayak chap17 src]$ ./combobox [a 
Twelfth Night 


combobox 





Tweltth Night| X | 





Macbeth | 

















Figure 17-6 


How It Works 


Create combo box widgets much like you create any other widget. The key new element lies in calling 
the insertStrList function to store the list of combo box choices. 


Like other text-holding widgets, you can set up a function to get called whenever the value, or more 
generically, the text, of the combo box changes. 


QListView 


Lists and trees in Qt are provided by the QListView widget. QListView displays both plain lists and hier- 
archical data divided into rows and columns. It’s perfect for displaying things like directory structures, 
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because the child elements can be expanded and contracted by clicking the plus and minus boxes, just like 
a file viewer. 


Unlike the GTK+ ListView widget, QListView handles both the data and the view, which makes for 
ease of use if not outstanding flexibility. 


With QListView, you can select rows or individual cells; then cut and paste the data, sort by column, 
and you'll have QCheckBox widgets rendered in cells. There’s a great amount of functionality built in — 
all you need to do as a programmer is add data and set up some formatting rules. 


Creating a QListView is done in the usual fashion, specifying the parent and widget name: 
QListView *view = new QListView(parent, "name"); 
To set column headings, use the aptly named addcolumn method: 


view->addColumn ("Left Column", widthl ); // Fixed width 
view->addColumn("Right Column"); // Width autosizes 


The column’s width is set in pixels or, if omitted, defaults to the width of the widest element in the 
column. The column will then autosize as elements are added and removed. 


Data is added to the QListView using a QListViewLItem object to represent a row of data. All you need 
do is pass the QListView and row elements to the constructor, and it’s appended to the view for you: 


QListViewItem *toplevel = new QListViewItem(view, "Left Data", "Right Data"); 


The first parameter is either a QListView, as in this case, or another QListViewItem. If you pass a 
QListViewLtem, the row appears as the child of that QListViewItem. The tree structure is therefore 
formed by passing the QListView for top-level nodes and then successive QListViewItems for the 
child nodes. 


The remaining parameters are the data for each column that default to NULL if not specified. 


Adding a child node is then just a case of passing in the top-level pointer. If you aren’t adding further 
child nodes to a QListViewItem, you needn’t store the returned pointer: 


new QListViewItem(toplevel, "Left Data", "Right Data"); // A Child of toplevel 


If you look at the QListViewItem API, you can see the methods to traverse the tree, should you wish to 
modify particular rows: 


#include <qlistview.h> 


virtual void insertItem ( QListViewItem * newChild ) 
virtual void setText ( int column, const QString & text ) 
virtual QString text ( int column ) const 

QListViewItem *firstChild () const 

QListViewItem *nextSibling () const 

QListViewItem *parent () const 

QListViewItem *itemAbove () 

QListViewItem *itemBelow () 
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You can get the first row in the tree by calling £irstChild on the QListView itself. You can then repeat- 


edly call £irstChild and nextSibling to return parts or the entire tree. 
This code snippet prints out the first column of all the top-level nodes: 
QListViewItem *child = view->firstChild() ; 
while (child) 
{ 
cout << myChild->text(1) << "\n"; 
myChild = myChild->nextSibling(); 
} 


You can find all the details about QListView, QhListViewItem, and QCheckListView in the Qt API 
documentation. 


Try It Out QListView 
In this Try It Out, you put everything together and write a short example of a QListView widget. 
Let’s skip the header file for brevity and see the class implementation, ListView. cpp: 


#include "ListView.moc" 





ListView: :ListView(QWidget *parent, const char *name) : QMainWindow(parent, name) 
{ 
listview = new QListView(this, "listviewl"); 


listview->addColumn("Artist"); 
listview->addColumn ("Title"); 
listview->addColumn ("Catalogue"); 


listview->setRootIsDecorated (TRUE) ; 


QListViewItem *toplevel = new QListViewItem(listview, "Avril Lavigne", 
"Let Go", "AVCD01"); 


new QListViewItem(toplevel, "Complicated"); 
new QListViewItem(toplevel, "Sk8er Boi"); 


setCentralWidget (listview) ; 
} 
int main(int argc, char **argv) 
{ 

QApplication app(argc, argv) ; 


ListView *window = new ListView(); 


app.setMainWidget (window) ; 
window->show() ; 


return app.exec(); 
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How It Works 


The QListView widget seems complicated in that it acts as both a list of items as well as a tree of items. 
Your code needs to create QListViewItem instances for each item you want in the list. Each of these 
QListViewLtem instances has a parent. Those items with the widget itself as the parent appear as top- 
level items. Items with another QListViewItem as a parent appear as child items. This example shows 
QListViewlLtem instances just one level deep, but you can create far deeper trees of items. 


After compiling and running the ListView example, you see the QListView widget in action as shown 
in Figure 17-7. 











Artist Title | Catalogue | 
=-Avril Lavigne Let Go AVCDO1 
+- Complicated 
Sk8er Boi 
Figure 17-7 


Note how the child rows are indented with respect to their parent. The plus and minus boxes 
indicating there are hidden or collapsible rows are not present by default; here you set them with 
setRootIsDecorated. 


Dialogs 


Up until now, you’ve been subclassing QMainWindow to create your interfaces. QMainWindow is appro- 
priate for the primary window in your application, but for short-lived dialogs, you should look at using 
the QDialog widget. 


Dialogs are useful whenever you want the user to input specific information for a particular task, or 
impart small amounts of information to the user, such as a warning or error message. It’s preferable to 
subclass QDialog for these tasks because you get convenient methods for running the dialog and pur- 
pose-designed signals and slots to handle the user response. 


As well as the usual modal and nonmodal (or modeless in Qt-speak) dialogs, Qt also offers a semimodal 
dialog box. The following list is a reminder of the differences between modal and nonmodal, and includes 
semimodal as well: 


Q Modal dialog box: Blocks input to all other windows to force the user to respond to the 


dialog. Modal dialogs are useful for grabbing an immediate response from the user and dis- 
playing critical error messages. 
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Q Nonmodal dialog box: Nonblocking window that operates normally with other windows in the 
application. Nonmodal dialog boxes are useful for search or input windows where you might 
want to copy and paste values to and from the main window, for instance. 





Q Semimodal dialog box: A modal dialog that does not have its own event loop. This enables con- 
trol to be returned to the application, but to still have input blocked to anything other than the 
dialog box. A semimodal dialog is useful in the rare occasions when you have a progress meter 
indicate the progress of time-consuming critical operation that you want to give the user the 
opportunity to cancel. Because it doesn’t have its own event loop, you must call 
QApplication: :processEvents periodically to update the dialog. 


QDialog 


QDialog is the base dialog class in Ot that provides exec and show methods for handling modal and 
nonmodal dialogs, has an integral QLayout you can use, and has several signals and slots useful for 
responding to button presses. 


You'll normally create a class for your dialog, inherit from QDialog, and add widgets to create the 
dialog interface: 


#include <qdialog.h> 


MyDialog: :MyDialog(QWidget *parent, const char *name) : QDialog(parent, name) 
{ 
QHBoxLayout *hbox = new QHBoxLayout (this) ; 


hbox->addWidget 
hbox->addWidget 
hbox->addWidget 


new Qlabel("Enter your name")); 
new QLineEdit()); 
ok_pushbutton) ; 





hbox->addWidget (cancel_pushbutton) ; 
connect (ok_pushbutton, SIGNAL(clicked()), this, SLOT(accept())); 
connect (cancel_pushbutton, SIGNAL(clicked()), this, SLOT(reject())); 


Unlike with the QMainWindow, you can directly specify MyDialog as the parent of your QLayout object 
without creating a dummy QWidget and using that as the parent. 


Note that this example omits the code to create the ok_pushbutton and cancel_pushbutton widgets. 


QDialog has two slots — accept and reject — that are used to indicate the dialog result. This result is 
returned by the exec method. Normally, you'll connect OK and Cancel buttons to the slots, as in MyDialog. 


Modal Dialogs 


To use your dialog as a modal dialog, you call exec, which brings up the dialog and returns either 
QDialog: :Accepted or QDialog: :Rejected according to which slot was activated: 


MyDialog *dialog = new MyDialog (this, "mydialog"); 
if (dialog->exec() == QDialog: :Accepted) 
{ 

// User clicked 'Ok' 
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doSomething() ; 

} 

else 

{ 
// user clicked 'Cancel' or dialog killed 
doSomethingElse() ; 

} 

delete dialog; 





The dialog is automatically hidden when the exec returns, but you still delete the object from memory. 


Note that all processing is blocked when exec is called, so if there is any time-critical code in your appli- 
cation, a nonmodal or semimodal dialog is more appropriate. 


Nonmodal Dialogs 


Nonmodal dialogs are little different from ordinary main windows, the key difference being that they 
position themselves over their parent window, share their taskbar entry, and hide automatically when 
the accept or reject slot is called. 


To display a nonmodal dialog, call show as you would a QMainWindow: 


MyDialog *dialog = new MyDialog(this, "mydialog"); 
dialog->show/() ; 


The show function displays the dialog and immediately returns to continue the processing loop. To handle 
button presses you need to write and connect to slots: 


MyDialog: :MyDialog(QWidget *parent, const char *name) : QDialog(parent, name) 
{ 

connect (ok_pushbutton, SIGNAL(clicked()), this, SLOT(OkClicked())); 

connect (cancel_pushbutton, SIGNAL(clicked()), this, SLOT(CancelClicked())); 


} 


MyDialog: :OkClicked() 
{ 
//Do some processing 


} 
MyDialog: :CancelClicked() 
{ 
//Do some other processing 
} 


The dialog is again automatically hidden when a button is pressed, as with a modal dialog. 


Semimodal Dialog 


To create a semimodal dialog you must set the modal flag in the QDialog constructor and use the 
show method: 


QDialog (QWidget *parent=0, const char *name=0, bool modal=FALSE, WFlags f=0) 
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The reason you didn’t set modal to TRUE with the modal dialog is that calling exec forces the dialog to 
be modal regardless of this flag. 


Your dialog constructor will look something like this: 





MySMDialog: :MySMDialog(QWidget *parent, const char *name) :QDialog(parent, name, TRUE) 
{ 


} 


Once you've got your dialog defined, you call show as normal and then progress with your processing, 
periodically calling QApplication: :processEvents to keep the dialog updated: 


MySMDialog *dialog = MySMDialog(this, "Ssemimodal") ; 
dialog->show() ; 
while (processing) 
{ 

doSomeProcessing() ; 

app->processEvents(); 

if (dialog->wasCancelled() ) 

break; 


Check that the dialog hasn’t been canceled before continuing processing. Note that wasCancelled isn’t 
part of QDialog — you have to provide that yourself. 


Qt provides ready-made subclasses of QDialog, specialized for particular tasks such as a file selec- 


tion, text entry, progress meter, and message box. Using these widgets whenever you can saves you a 
lot of trouble. 


QMessageBox 


A QMessageBox is a modal dialog that displays a simple message with an icon and buttons. The icon 


depends on the severity of the message, which can be regular information or warnings and other critical 
information. 


The QMessageBox class has static methods to create and show each of these three types: 
#include <qmessagebox.h> 


int information (QWidget *parent, const QString &caption, const QString &text, 
int button0, int button1=0, int button2=0) 


int warning (QWidget *parent, const QString &caption, const QString &text, 
int button0, int buttonl, int button2=0) 
int critical (QWidget *parent, const QString &caption, const QString &text, 


int button0, int buttonl, int button2=0) 


You can choose buttons from a list of stock QMessageBox buttons, which match up with the returned 
value of the static methods: 


m) QMessageBox: :Ok 





QO QMessageBox: :Cancel 
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QMessageBox: : Yes 
QMessageBox: :No 
QMessageBox: :Abort 


QMessageBox: :Retry 


Oocovco sob 


QMessageBox: : Ignore 
A typical use of (MessageBox will look something like this: 


int result = QMessageBox: :information(this, 


"Engine Room Query", "Do you wish to engage the HyperDrive?", 
QMessageBox: : Yes | QMessageBox: :Default, 
QMessageBox: :No | QMessageBox: : Escape) ; 


switch (result) { 
case QMessageBox: : Yes: 
hyperdrive->engage() ; 
break; 
case QMessageBox: :No: 
// do something else 
break; 


You OR the button codes with Default and Escape to set the default actions when the Enter (or Return) 
and Escape buttons are pressed on the keyboard. Figure 17-8 shows the resulting dialog. 


= Engine Room Query 





f x 


4) Do you wish to engage the HyperDrive? 
bra 

















Figure 17-8 


QInputDialog 


QInputDialog is useful for inputting single values from the user, which can either be text, an option 
from a drop-down list, an integer, or a floating-point value. The QInputDialog class has static methods 
like QMessageBox that are a bit of a handful because they have many parameters, but fortunately most 
have default values. 


#include <qinputdialog.h> 

QString getText (const QString &caption, const QString é&label, 
QLineEdit::EchoMode mode=QLineEdit: :Normal, 
const QString &text=QString::null, bool * ok = 0, 


QWidget * parent = 0, const char * name = 0) 


QString getItem (const QString &caption, const QString é&label, 
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const QStringList &list, int current=0, bool editable=TRUE, 
bool * ok=0, QWidget *parent = 0, const char *name=0) 


int getInteger (const QString &caption, const QString &label, int num=0, 
int from = -2147483647, int to = 2147483647, int step = 1, 
bool * ok = 0, QWidget * parent = 0, const char * name = 0) 


double getDouble (const QString &caption, const QString &label, double num = 0, 
double from = -2147483647, double to = 2147483647, 
int decimals = 1, bool * ok = 0, QWidget * parent = 0, 
const char * name = 0 ) 


To input a line of text, you can write this: 


bool result; 

QString text = QInputDialog::getText("Question", "What is your Quest?:", 
QLineEdit::Normal, 
(OVSicresvaves ginUlil, facerswwilic,, EEAS Talieyoywie™ ))-e 

if (result) { 

doSomething (text) ; 

} else { 

// user pressed cancel 

} 


QInputDialog is made up of a QLineEdit widget and OK and Cancel buttons, as you see in Figure 17-9. 





What is your Quest?: 


to find the grail. 





OK | Cancel 











Figure 17-9 


The dialog created by QInputDialog: :getText uses a QLineEdit widget. The edit mode parameter 
you pass to the getText function controls how the text will be echoed back to the user, exactly like the 
same mode for the QLineEdit widget. You can also specify default text or set it to empty as shown here. 
Every QInputDialog has OK and Cancel buttons, and passes a bool pointer to the method to indicate 
which button was pressed — result is TRUE if the user clicks OK. 








getItem offers the user a list of options through a QComboBox: 


bool result; 
QStringList options; 
options << "London" << "New York" << "Paris"; 
QString city = QInputDialog::getItem("Holiday", "Please select a destination:", 
options, 1, TRUE, &result, this, "combo"); 
if (result) 
selectDestination(city); 


The resulting dialog is shown in Figure 17-10. 
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Please select a destination: 


| Paris| 











OK Cancel 














Figure 17-10 


getInteger and getDouble work in much the same way, so we won’t expand on them here. 


Using qmake to Simplify Writing Makefiles 


Compiling applications with both the KDE and Qt libraries becomes quite a chore because your makefile 
gets ever more complicated with the need to use moc and having libraries here, there, and everywhere. 
Fortunately, Qt comes with a utility called qmake to create makefiles for you. 


If you've used Qt before, you may be familiar with tmake — an earlier (and now deprecated) incarna- 
tion of qmake that shipped with previous versions of Qt. 


qmake takes a .pro file as input. This file contains the very basic information that the compilation 
requires, such as the sources, headers, target binary, and KDE/Qt library locations. 


A typical KDE .pro file looks like this: 


TARGET = app 

MOC_DIR = moc 

OBJECTS_DIR = obj 

INCLUDEPATH = /usr/include/kde 
QMAKE LIBDIR X11 += /usr/lib 

QMAKE LIBS X11 += -lkdeui -lkdecore 
SOURCES = main.cpp window.cpp 
HEADERS = window.h 











You specify the target binary, temporary moc and object directories, the KDE library path, and the sources 
and headers to build from. Note that the location of the KDE header and library files depends on your 
distribution. SUSE users should set INCLUDEPATH to /opt/kde3 /include and QMAKE_LIBS_X11 to 


/opt/kde3/1lib. 
$ qmake file.pro -o Makefile 


Then you can run make as normal; it’s that straightforward. For a KDE/Qt program of any complexity, 
you should use qmake to simplify the build routine. 


Menus and Toolbars with KDE 


As a demonstration of the power of KDE widgets, we’ve saved menus and toolbars to describe last, 
because they’re a pretty good example of how the KDE libraries save time and effort compared to using 


plain Qt or other graphical user interface toolkits. 
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Usually in GUI libraries, menu items and toolbar items are distinct elements, each with their own item 
widgets. You have to create separate objects for each entry and keep track of changes; for example, dis- 
abling certain options individually. 


The KDE programmers came up with a better solution. Instead of this detached approach, KDE defines 
a KAction widget to represent an action that the application can perform. This action could be opening a 
new document, saving a file, or showing a help box. 


The KAction is given text, a keyboard accelerator, an icon, and a slot that’s called when the KAction 
is activated: 


KAction *new_file = new KAction("New", "filenew", 
KstdAccel::shortcut (KstdAccel: :New), 
this, SLOT(newFile()), this, "newaction") ; 


The KAction can then be plugged into a menu and toolbar without any further description: 


new_file->plug(a_menu) ; 
new_file->plug(a_toolbar) ; 


You’ve now created a New menu and toolbar entry that calls newFile when clicked. 


Now if you need to disable the KAction — say if you don’t want the user to be able to create a new 
file — the call is centralized: 


new_file->setEnabled(FALSE) ; 


That’s all there is to menus and toolbars with KDE — it’s very easy indeed. Take a look at the KAction 
constructor: 


#include <kde/kaction.h> 


KAction (const QString &text, const KShortcut &cut, const QObject *receiver, 
const char *slot, QObject *parent, const char *name = 0) 


KDE provides you with standard KAction objects to make sure text, icons, and keyboard accelerators 
are standard between KDE applications: 


#include <kde/kaction.h> 


KAction * openNew (const QObject *recvr, const char *slot, 
KActionCollection* parent, 
const char *name = 0 ) 

KAction * save ... 

KAction * saveAs ... 

KAction * revert ... 

KAction * close ... 

KAction * print ... 

etc... 
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Each standard action takes the same parameters: the slot receiver and function, a KActionCollection, 
and the KAction name. The KActionCollection object manages the KActions in a window, and you 
can get the current object using the actionCollection method of KMainWindow: 


KAction *saveas = KStdAction::saveAs(this, SLOT(saveAs()), actionCollection(), 
"saveas"); 


Try It Out A KDE Application with Menus and Toolbars 


You try using KActions in a KDE application with this next example. 


1. Start with the header file KDEMenu . h. KDEMenu is a subclass of KMainWindow, itself a subclass 
of QMainWindow. KMainWindow handles session management within KDE and has an integral 
toolbar and status bar. 





#include <kde/kmainwindow.h> 


class KDEMenu : public KMainWindow 
{ 
Q OBJECT 


public: 
KDEMenu(const char * name = 0); 


private slots: 
void newFile(); 
void aboutApp(); 
i 


2. In KDEMenu. cpp, start with #include directives for the widgets you'll be using: 
#include "KDEMenu.h" 


#include <kde/kapp.h> 
#include <kde/kaction.h> 
#include <kde/kstdaccel .h> 
#include <kde/kmenubar .h> 
#include <kde/kaboutdialog.h> 


3. In the constructor, create three KAction widgets. new_file is created using a manual definition 
and quit_action and help_action use standard KAction definitions: 


KDEMenu: :KDEMenu (const char *name = 0) : KMainWindow (0L, name ) 
{ 
KAction *new_file = new KAction("New", "filenew", 
KstdAccel::shortcut (KstdAccel: :New), 
this, SLOT(newFile()), this, "newaction"); 


KAction *quit_action = KStdAction::quit (KApplication::kApplication(), 
SLOT(quit()), actionCollection()); 


KAction *help_action = KStdAction::aboutApp(this, SLOT(aboutApp()), 
actionCollection()); 
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4. Create two top-level menus and insert them into the KApplication menuBar: 


QPopupMenu *file_menu = new QPopupMenu; 
QPopupMenu *help_menu = new QPopupMenu; 


menuBar ()->insertItem("&File", file menu) ; 
menuBar()->insertItem("&Help", help_menu) ; 


5. Now plug the actions in the menus and toolbar, inserting a separator line between new_file 
and quit_action: 


new_file->plug(file_menu) ; 

file_menu->insertSeparator () ; 
quit_action->plug(file_menu) ; 
help_action->plug (help_menu) ; 


new_file->plug(toolBar()); 
quit_action->plug(toolBar()) ; 


6. Finally some slot definitions: aboutApp creates a KAbout dialog to display information about 
the program. Note that the quit slot is defined as part of KApplication: 





void KDEMenu: :newFile() 
{ 

// Create new File 
} 


void KDEMenu: :aboutApp () 

{ 
KAboutDialog *about = new KAboutDialog(this, "dialog"); 
about->setAuthor (QString("A. N. Author"), QString("an@email.net"), 

QString("http://url.com"), QString("work") ) ; 

about->setVersion("1.0"); 

about->show() ; 





} 


int main(int argc, char **argv) 


{ 
KApplication app( argc, argv, "cdapp" );; 
KDEMenu *window = new KDEMenu("kdemenu") ; 
app.setMainWidget (window) ; 
window->show() ; 
return app.exec(); 

} 


7. Next you need a menu. pro file for qmake: 


TARGET = kdemenu 
MOC_DIR = moc 
OBJECTS_DIR = obj 
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INCLUDEPATH = /usr/include/kde 
QMAKE LIBDIR_ X11 += -LSKDEDIR/1lib 
QMAKE LIBS_X11 += -lkdeui -lkdecore 
SOURCES = KDEMenu.cpp 

HEADERS = KDEMenu.h 











8. Now run amake to create your Makefile, compile, and run. 


$ qmake menu.pro -o Makefile 
$ make 
$ ./kdemenu 


How It Works 


Though this example appears longer than the other examples, the code is relatively terse for all the work 
it does creating a menu bar and menus. The best part of the KAct ion widgets is that you can use each one 
in multiple places, such as on the toolbar and in a menu on the menu bar, both shown in this example. 


Building KDE applications requires more work than building most programs, at least at first glance. In 
reality, the menu. pro file and the gmake command hide a large number of settings you would otherwise 


have to place manually in your makefile. 


Figures 17-11 and 17-12 show how the menus and toolbar buttons appear in the window. 


i kdemenu 20x 





File Help 





Figure 17-11 


| kdemenu oox 





File) Help 


E Quit Ctri+Q 





Figure 17-12 


And that’s it! We’ve finished the tour of Qt and KDE, looking at the basic elements of all GUI applica- 
tions, windows, layouts, buttons, dialogs, and menus. There are countless Qt and KDE widgets we 
haven’t covered, from QColorDialog — a color-choosing dialog — to KHTML — a Web browser 
widget — all fully documented on the Trolltech and KDE websites. 
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CD Database Application Using KDE/Qt 


It’s time to turn your attention to the CD application once again, now that you can use the power of 
KDE/(Qt to bring it to life. You'll follow the same layout as in Chapter 16 and code similar functionality. 


Remember what you want your CD database application to do: 


Log on to the database from the GUI 
Search for a CD 

Display CD and track information 
Add a CD to the database 





Cocoo do 


Display an About window 


MainWindow 


Start off with coding the main window of your application, which contains the search entry widget and 
search result list. 


1. Start by typing in the code for MainWindow.h (or downloading it from the book’s website). 
Because the window contains a QLineEdit widget for searching for CDs and a QListView to 
display the results, you need to include the qlistview.h and qlineedit .h header files: 


#include <kde/kmainwindow.h> 
#include <qlistview.h> 
#include <qlineedit.h> 


class MainWindow : public KMainWindow 


£ 
Q_OBJECT 





public: 
MainWindow (const char *name); 


public slots: 
void doSearch() ; 
void Addcd(); 


private: 
QListView *list; 
QLineEdit *search_entry; 





2. MainWindow.cpp is the most complicated part of the program. In the constructor, you create the 
main window interface and connect the necessary signals to your slots. As usual, start off with 
the #include files: 


#include "MainWindow.h" 


#include "AddCdDialog.h" 
#include "app_mysql.h" 
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#include 
#include 
#include 
#include 
#include 
#include 
#include 
#include 
#include 
#include 
#include 
#include 


#include 


MainWindow: :MainWindow ( const char * name ) : KMainWindow 


{ 
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<qvbox. h> 
<qlineedit.h> 
<qpushbutton.h> 
<qlabel .h> 
<qlistview.h> 
<kde/kapp.h> 
<kde/kmenubar . h> 
<kde/klocale.h> 
<kde/kpopupmenu . h> 
<kde/kstatusbar.h> 
<kde/kaction.h> 
<kde/kstdaccel .h> 


<string.h> 


setCaption("CD Database") ; 


Now create your menu and toolbar entries using the KAction widget: 


KAction *addcd_action = new KAction("&Add CD", 


KStdAccel: : shortcut (KStdAccel: :New) , 


this, 
SLOT (Addcd()), 
Shae > 


name ) 


KAction *quit_action = KStdAction::quit (KApplication::kApplication(), 


SLOT(quit()), actionCollection()); 


QPopupMenu * filemenu = new QPopupMenu; 
QString about = ("CD App\n\n" 


QPopupMenu *helpmenu 


"(C) 2007 Wrox Press\n" 
"email@email.com\n") ; 


helpMenu (about) ; 


menuBar()->insertItem( "&File", filemenu) ; 
( 


menuBar ()->insertItem(i1l8n("&Help"), helpmenu) ; 


addcd_action->plug(filemenu) ; 
filemenu->insertSeparator(); 
quit_action->plug(filemenu) ; 


addcd_action->plug(toolBar()) ; 
quit_action->plug(toolBar()); 


In the interest of variety, you'll use QBox layout widgets instead of the usual QLayout classes: 


QVBox *vbox new QVBox (this); 
QHBox *hbox = new QHBox (vbox) ; 
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6. 


QLabel *label = new Qhabel (hbox); 
lelgjeil=Seeiemerac (( “Siseucicla, mesta" Jp 


search_entry = new QLineEdit ( hbox ); 
QPushButton *button = new QPushButton( "Search", hbox); 


Next up is the QListView widget, which occupies the majority of the window area. Then you 
connect the requisite signals to your doSearch slot to perform the CD database search. The 
KMainWindow status bar is made visible by adding an empty message: 


list = new QListView( vbox, "name", OL); 
list->setRootIsDecorated (TRUE) ; 
list->addColumn ("Title"); 
list->addColumn ("Artist"); 
list->addColumn ("Catalogue"); 


connect (button, SIGNAL (clicked()), this, SLOT (doSearch())); 
connect (search_entry , SIGNAL(returnPressed()), this, SLOT(doSearch())); 


statusBar ()->message("") ; 
setCentralWidget (vbox) ; 
resize (300,400); 


The doSearch slot is the business end of the application. It reads the search string and fetches 
all matching CDs and their tracks. The logic is identical to the GNOME/GTK+ doSearch func- 
tion in Chapter 16. 


void MainWindow: :doSearch () 


{ 


cd_search_st *cd_res = new cd_search_st; 
current_cd_st *cd = new current_cd_st; 
struct current_tracks_st ct; 

sale SeeSul, aby, apy Sse, ilesisip 

char track_title[110]; 

char search_text[100]; 

char statusBar_text[200]; 

QListViewItem *cd_item; 


strcpy (search_text, search_entry->text()); 


Fetch the matching CD ids and update the status bar to display the search results: 


resl = find_cds (search_text, cd_res); 

sprintf (statusBar_text, " Displaying %d result(s) for search string ' %s '", 
resl, search_text); 

statusBar ()->message(statusBar_text) ; 


i = Os 
list->clear(); 
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8. Foreach id, get the CD information, insert into the QListView, and get all tracks for this CD: 
whibe: (i = peel) 4 
res2 = get_cd(cd_res->cd_id[i], cd); 
cd_item = new QListViewItem(list, cd->title, cd->artist_name, cd->catalogue) ; 
res3 = get_cd_tracks(cd_res->cd_id[i++], &ct); 
J Os 
/* Populate the tree with the current cd's tracks */ 


while (j < res3) { 


spriner(eracki titler ” Ubgevele Excl, ©, Sjabil))e 
streat(track_title, ct.track[jt++]); 


new QListViewItem(cd_item, track_title); 
} 


} 
9. The addcad slot is called when the addcd_act ion menu item or toolbar button is activated: 


void MainWindow: :Addcd() 

{ 
AddCdDialog *dialog = new AddCdDialog(this) ; 
dialog->show() ; 

} 


The result is shown in Figure 17-13. 


CD Database 





Eile Help 


Search Text: Pink Search 











Title Artist Catalogue | 
Pink Floyd B000024D4P 
_ Pink Floyd BO00024D4S 









jWish You Were Here 


Track 1. Shine on you crazy diamond 


Track 2. Welcome to the machine 

Track 3. Have a cigar 

Track 4. Wish you were here 

Track 5. Shine on you crazy diamond pt.2 








Displaying 2 result(s) for search string ' Pink ' 


Figure 17-13 
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AddCdDialog 


To add a CD to the database, you'll need to code a dialog with the necessary fields you need to input. 


1. Enter the following code and call it AddcdDialog.h. Note that AddcdDialog inherits from 
KDialogBase, the KDE dialog widget. 


#include <kde/kdialogbase.h> 
#include <qlineedit.h> 


class AddCdDialog : public KDialogBase 
{ 
Q_ OBJECT 





public: 
AddCdDialog (QWidget *parent) ; 


private: 
QLineEdit *artist_entry, *title_entry, *catalogue_entry; 


public slots: 
void okClicked(); 
IPB 


2. Next is AddCdDialog. cpp, which calls the add_cd function from the MySQL interface code in 
the okClicked slot: 


#include "AddCdDialog.h" 
#include "app_mysql.h" 


#include <qlayout.h> 
#include <qlabel.h> 


AddCdDialog: :AddCdDialog( QWidget *parent) 
: KDialogBase( parent, "AddCD", false, "Add CD", 
KDialogBase: :Ok|KDialogBase::Cancel, KDialogBase::0k, true ) 


QWidget *widget = new QWidget (this); 

setMainWidget (widget) ; 

QGridLayout *grid = new QGridLayout (widget,3,2,10, 5,"grid"); 
grid->addWidget (new QLabel("Artist", widget, "artistlabel"), 0, 0, 0); 
grid->addWidget (new QLabel("Title", widget, "titlelabel"), 1, 0, 0); 
grid->addWidget (new QLabel ("Catalogue", widget, "cataloguelabel"), 2, 0, 0); 
artist_entry = new QLineEdit( widget, "artist_entry"); 

title_entry = new QLineEdit( widget, "title_entry"); 


catalogue_entry = new QLineEdit( widget, "catalogue_entry") ; 


grid->addWidget(artist_entry, 0,1, 0); 
grid->addWidget (title_entry, 1,1, 0); 
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grid->addWidget (catalogue_entry, 2,1, 0); 


connect (this, SIGNAL(okClicked()), this, SLOT(okClicked())); 
} 


void AddCdDialog: :okClicked() 
{ 

char artist[200]; 

char title[200]; 

char catalogue[200]; 

sine Coie = Op 


strcpy (artist, artist_entry->text()); 
strcpy (title, title_entry->text()); 

strcpy (catalogue, catalogue_entry->text()); 
add_cd(artist, title, catalogue, &cd_id); 


Figure 17-14 shows the AddCdDialog in action. 





Artist Spinal Tap 


Title Smell the Glove 


Catalogue |B0000564P| 


Y OK 3X Cancel 








Figure 17-14 


LogonDialog 


Of course, you can’t query the database without first logging on, so you need a simple dialog to enter 
your credentials. Call this class LogonDialog. (Yes, another subtle and imaginative title!) 


1. First, the header file. Enter this, calling it LogonDialog.h. Note that for variety this time you 
inherit from QDialog rather than KDialogBase. 


#include <qdialog.h> 
#include <qlineedit.h> 


class LogonDialog : public QDialog 
{ 
Q OBJECT 


public: 
LogonDialog (QWidget *parent = 0, const char *name = 0); 
QString getUsername() ; 
QString getPassword() ; 
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private: 
QLineEdit *username_entry, *password_entry; 


2. Rather than encapsulating the database_start call in LogonDialog.cpp, you have better 
methods for the username and password. Here’s LogonDialog. cpp: 


#include "LogonDialog.h" 
#include "app_mysql.h" 


#include <qpushbutton.h> 
#include <qlayout.h> 
#include <qlabel.h> 


LogonDialog::LogonDialog( QWidget *parent, const char *name): QDialog(parent, name) 


{ 
QGridLayout *grid = new QGridLayout(this, 3, 2, 10, 5,"grid"); 
grid->addWidget (new QLabel("Username", this, "usernamelabel"), 0, 0, 0); 
grid->addWidget (new QLabel("Password", this, "passwordlabel"), 1, 0, 0); 


username_entry = new QLineEdit( this, "username_entry") ; 
password_entry = new QLineEdit( this, "password_entry") ; 
password_entry->setEchoMode (QLineEdit: : Password) ; 








grid->addWidget (username_entry, 0, 1, 0); 
grid->addWidget (password_entry, 1, 1, 0); 


QPushButton *button = new QPushButton ("Ok", this, "button"); 
grid->addWidget (button, 2, 1,Qt::AlignRight) ; 


connect (button, SIGNAL(clicked()), this, SLOT(accept())); 
} 
QString LogonDialog: :getUsername () 
i if (username_entry == NULL) 


return NULL; 


return username_entry->text (); 


} 
QString LogonDialog: :getPassword() 
{ 
if (password_entry == NULL) 
return NULL; 


return password_entry->text (); 


} 


Figure 17-15 shows how the dialog will look. 
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Username [andrew 


Lok | 





Figure 17-15 


main.cpp 


The only remaining code is the main function that you place in a separate source file, main. cpp. 


1.  Inmain.cpp, you open a LogonDialog and get a successful logon from database_start. If 
logging on isn’t successful, you display a QMessageBox, or if you try to exit the LogonDialog, 


ask the users to confirm that they want to quit. 


#include "MainWindow.h" 
#include "app_mysql.h" 
#include "LogonDialog.h" 


#include <kde/kapp.h> 


#include <qmessagebox.h> 


int main( int argc, char **argv ) 
{ 

char username[100]; 

char password[100]; 


KApplication a( argc, argv, "cdapp" ); 


LogonDialog *dialog = new LogonDialog(); 


while (1) 

{ 
if (dialog->exec() == QDialog: :Accepted) 
{ 


strcpy (username, dialog->getUsername()) ; 
strcpy (password, dialog->getPassword() ) 


1 


if (database_start (username, password) ) 
break; 


QMessageBox: :information(0, "Title", 
"Could not Logon: Check username and/or password", 
QMessageBox: :Ok) ; 
continue; 
} 
else 
{ 
if (QMessageBox::information(0, "Title", 
"Are you sure you want to quit?" 
QMessageBox::Yes, QMessageBox: :No) 
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== QMessageBox: : Yes) 
{ 
return 0; 
} 
} 
} 
delete dialog; 


MainWindow *window = new MainWindow( "Cd App" ); 
window->resize( 600, 400 ); 


a.setMainWidget ( window ); 
window->show() ; 


return a.exec(); 


2. All that remains is to write a . pro file to pass to qmake. Call this cdapp. pro: 


TARGET = app 

MOC_DIR = moc 

OBJECTS_DIR = obj 

INCLUDEPATH = /usr/include/kde /usr/include/mysql 

QMAKE LIBDIR_X11 += -/usr/lib 

QMAKE_LIBDIR_X11 += /usr/lib/mysql 

QMAKE_LIBS_X11 += -lkdeui -lkdecore -lmysqlclient 

SOURCES = MainWindow.cpp main.cpp app_mysql.cpp AddCdDialog.cpp LogonDialog.cpp 
HEADERS = MainWindow.h app_mysql.h AddCdDialog.h LogonDialog.h 











Note that the code lets you cheat slightly by simply renaming app_mysq1 .c to app_mysql . cpp; 
therefore, you can treat it like an ordinary C++ source file. This avoids the (minor) complication of hav- 
ing to link a C object file to C++. 


$ qmake cdapp.pro -o Makefile 
$ make 


$ ./app 


If all is well, you should have a working CD database! 


You might like to try implementing the other functions in the MySQL interface, such as adding tracks to 
CDs or deleting CDs, to get a closer understanding of KDE/Qt. You'll need to create dialog boxes, new 


menu entries, and toolbar entries, and you'll have to write the underlying logic. Give it a shot! 


Summary 


In this chapter, you've learned about using the Qt GUI library and seen KDE widgets in action. You’ve 
seen that Qt is a C++ library that uses a signal/slot mechanism to implement event-driven programming. 
You took a tour of the basic Qt widgets and wrote several example programs to demonstrate how to use 


them in practice. Finally, you implemented a GUI front end to your CD application using KDE/Qt. 
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Standards for Linux 





Linux started as just a kernel. Unfortunately, a kernel on its own is not very useful; programs are 
needed for logging in, managing files, compiling new programs, and so forth. To make a useful 
system, tools were added from the GNU project. These were clones of familiar programs available 
on the UNIX and UNIX-like systems around at the time. Making Linux look and feel like UNIX set 
the first standards for Linux, providing a familiar environment for C programmers. 


Different UNIX (and later Linux) vendors added proprietary extensions to the commands and utilities 
they made available, and the layout of the file systems they used varied slightly. It became difficult to 
create applications that would work on more than one system. Even worse, a programmer could not 
even rely on system facilities being provided in the same way or configuration files being maintained 
in the same place. 


It was clear that some standardization was needed to prevent the UNIX systems from fragmenting, 
and some excellent UNIX standardization work is now in place. 


Over time not only have these standards moved forward, but Linux itself has been enhanced at 

an impressive speed by the community, often supported by commercial organizations like Red Hat 
and Canonical, and even non-Linux vendors such as IBM. As Linux has progressed, it, along with 
the gcc compiler collection, has not only tracked the relevant standards rather well, but has also 
defined new standards as existing standards have been found to be insufficient. Indeed, as Linux 
and its associated tools and utilities have become ever more popular, the UNIX vendors have 
started making changes to their UNIX offerings to make them more compatible with Linux. 


In this final chapter, we are going to look at these standards, pointing out areas that you should 
be aware of if you want not only to write applications that work on your Linux systems through 
upgrades, but also to create code that will be portable to other Linux distributions, and maybe 
even other UNIX-style systems, so that you can share your programs with others. 


In particular, we look at 


Q The C programming language standard 
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Q The UNIX standards, particularly the POSIX standard developed by the IEEE and The Single 
UNIX Specification developed by the Open Group 





Q Work by the Free Standards Group, particularly the Linux Standard Base, which defines a stan- 
dard Linux file system layout 


A good starting place for standards relating to Linux is the Linux Standard Base (LSB), which you can 
find from the Linux Foundation web site at http: //www. linux-foundation.org/. 


We are not going to look in detail at the contents of the standards; many of them are as long as this book. We 
are going to point out the key standards you should know about, give you a little historic background on 
how those standards arose, and help you decide which standards you might find helpful when writing your 
own programs. 


The C Programming Language 


The programming language C is the de facto language for programming Linux, so in order to write 
portable C programs for Linux, it’s worth understanding a little of its origins, how it has changed, and, 
most important, how to check that your program is conforming correctly to standards. 


A Brief History Lesson 


For those not enamored of history, don’t worry; because this book is about programming, not history, we 
will keep this discussion very brief. 


The C programming language dates from around 1970 and was based, in part, on the earlier programming 
language BCPL and extensions to the language B. Dennis M. Ritchie wrote a reference manual for the lan- 
guage in 1974, and C was used as the basis for a rewrite of the UNIX kernel on a PDP-11 around the same 
time. In 1978 Brian W. Kernighan and Ritchie wrote the classic reference book for the language, The C 
Programming Language. 


The language became very popular very quickly, influenced no doubt in part by the rapid growth in 
the popularity of UNIX, but also by its own power and clean syntax. The C language syntax continued 
to evolve by consensus, but as it diverged further and further from the language described in the origi- 
nal book, it became clear that a standard that was both consistent with current usage, and more pre- 
cise, was needed. 


In 1983 ANSI established the X3J11 standards committee to develop a clean and concise definition of 

the language. Along the way they made some minor additions to the language, particularly giving it the 
very welcome ability to declare the type of parameters, but in general the committee simply clarified and 
rationalized the existing definition of what constituted common usage of the language. The standard was 
finally published in 1989 as the ANSI standard Programming Language C, X3.159-1989, or more briefly 
C89, or sometimes C90. (This later became an ISO standard, ISO/IEC 9899:1990, Programming 
Languages — C. The two standards are technically identical.) 


As with most standards, publication did not end the work of the committee, which continued work on 
clarifying minor discrepancies found in the specification, and in 1993 started work on the next version of 
the standard, dubbed C9X. The committee also published minor corrections and updates to the current 
standard in 1994, 1995, and 1996. 
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The new edition of the standard just made it into the 1990s, and officially become the C99 standard; it 
was adopted by ISO as ISO/IEC 9899:1999. There is still a working committee, J11, looking at standardi- 
zation of the C language and its libraries, but it is now working under the InterNational Committee for 
Information Technology Standards group. You can find more details on the current standards work for 
Cathttp://j1l.incits.org/. 


The GNU Compiler Collection 


After developing the Emacs editor (yes, we love Emacs), the GNU project’s next major accomplishment, as 
discussed in Chapter 1, was a completely free C compiler, gcc, with the first official version released in 1987. 


Originally, gcc was the GNU C Compiler, but because the same basic compiler framework now supports 
many other languages, such as C++, Objective-C, FORTRAN, Java and Ada, as well as libraries for these 
languages, the definition has been adjusted to the more appropriate GNU Compiler Collection. 


gcc has always been, and looks set to remain, the standard compiler for Linux, and C or C++ the primary 
language for writing programs on Linux. You can find the gcc home page at http: //gcc.gnu.org/. 


The GNU C Compiler has always been good at accurately tracking the developing C standard, although it 
does allow some extensions, and there are inevitably slight delays, as with almost all compilers, between 
the standard’s becoming available and compilers that exactly implement that specification. Occasionally 
the opposite happens, and gcc anticipates that a standard will change slightly, which can also be quite 
confusing. gcc has a number of command-line and other options that allow you to specify the version of 
C standard you want gcc to conform to, as well as other options to control just how persnickety you 
would like the compiler to be. 


gcc Options 


Now that you know a little of the background of the C standard, let’s look at the options the gcc compiler 
offers for ensuring that the C you write conforms accurately to the language standard. There are three ways 
to ensure your C code is both in conformity with standards and clean: options that control the version of 
the standard you intend to be compatible with; defines to control header files; and warning options that 
invoke more stringent checking of the code. 


gcc has a huge range of options, and we look here only at the options we consider most important. You 
can find the full list of options on the gcc manual pages. We also look briefly at some additional #define 
options that can be used; these must normally be set in your source code before any #include lines or 
defined on the gcc command line. You might wonder why so many options are required for selecting the 
standard to use, rather than simply a flag that says to enforce the current standard. The reason is that 
many older programs rely on the historic behavior of the compiler and would require significant rework- 
ing to update them to the latest standards. Rarely, if ever, do we want a compiler update to start breaking 
working code. As the standards change, it’s important to be able to work against a defined standard, even 
if that is not always the very latest version of the standard. 


Even if you are just writing a small program for personal use, when maybe conforming to standards doesn’t 


seem that important, it can often be worth turning on more of gcc’s warnings to let the compiler find a mis- 
take in your code before you even run the program. This is always more efficient than stepping through 
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code in the debugger wondering where the problem might be. The compiler has many options that go well 
beyond simple checking for conformance to standards, such as the ability to spot code that does conform to 
the standard but may have dubious semantics. For example, there may be an order of execution that will 
allow a variable to be accessed before it is initialized. 


If you do need to write code for other people to use, then — having selected the level of standards com- 
pliance and compiler warning you think appropriate — it’s very important to put in that extra bit of 
effort to ensure that your code compiles with no warnings at all. If you allow some warnings to appear 
and make it a habit just to ignore them, then one day a more serious warning will appear that you may 
miss. If your code always compiles completely clean, a new warning will be obvious. Compiling clean 
code is a good habit to get into. 


Compiler Options for Standards Tracking 


These options are passed to gcc on the command line; we show only the most important options here: 


Q 


-ansi: This is the most important standards option, and tells the compiler to work to the ISO C90 
standard of the language. It turns off certain gcc extensions that are incompatible with the stan- 
dard, disables C++ (//) style comments in C programs, and enables the ANSI trigraph features. 
It also defines the macro __STRICT_ANSI__, which turns off some gcc extensions in header files 
that are incompatible with the standard. Later versions of the compiler may change the lan- 
guage standard targeted. 





-std=: This option allows more fine-grained control of the standard in use by supplying a 
parameter that sets the exact standard required. The main options are 


Q c89 supports the c89 standard. 
Q  iso9899:1999 supports the latest ISO C90 standard. 


Q gnu89 supports the C89 standard, but allows GNU extensions and some C99 features as 
well. As of version 4.2 of gcc this is the default behavior. 


Define Options for Standard Tracking 


These are constants (#defines) that can either be set by options on the compiler command line or, alter- 
natively, as definitions in the source code. We generally suggest using the compiler command line for 
these options. 


m) 


m) 


m) 





m) 
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STRICT_ANSI_: Force the use of ISO standard C. Defined when -ansi is given as a compile 
line option. 


_POSIX_C_SOURCE=2: Turn on features defined by the IEEE Std 1003.1 and 1003.2 standards. 
We mention these standards again later in this chapter. 


_BSD_SOURCE: This enables BSD-type features. If those features conflict with POSIX defini- 
tions, the BSD definitions take precedence. 





_GNU_SOURCE: Allows a wide range of features, including GNU extensions. If those features 
conflict with POSIX definitions, the POSIX definitions take precedence. 
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Compiler Options for Warnings 


These options are passed to the compiler on the command line. Again we just list the main options; you 
can find a full list in the gcc manual pages. 


ū -pedantic: This is the most powerful compiler option for checking clean C code. Apart from 
turning on the option to check for standard conformant C, it also turns off some traditional C 
constructs that are not permitted by the standard, and disables all the GNU extensions to the 
standard. This is the option to use if you want your C code to be as portable as possible. The 
downside is that the compiler is very fussy indeed about your code being clean, and sometimes 
it can require you to think very carefully in order to get rid of the last few warnings. 


Q = -Wformat: Checks that the argument types to the printf family of functions are correct. 


ū -Wparentheses: Checks that parentheses are always provided, even in some circumstances 
where they are not needed. This is quite a useful option for checking that initialization of 
complex structures is as intended. 


Q -Wswitch-default: Checks that all switch statements have a default case, which is generally 
good coding practice. 


Q -Wunused: Checks a variety of cases such as static functions declared but never defined, unused 
parameters, and discarded results. 


Q = -Wall: Turns on most of gcc’s warnings, including all of the preceding -w options (it does not 
select -pedantic) and is a good way to keep your code clean. 


There are many, many more warning options; see the gcc web pages for the full details. In general we 
suggest you use -Wa11; it’s a good compromise between checking for good quality code and having the 
compiler generate so many trivial warnings it becomes a serious impediment to keeping the number of 
warnings from the compiler to zero. 


Interfaces and the Linux Standards Base 


We are now going to move up a level from the raw C code and look at the interfaces (system functions) 
provided by the operating system. This level of standardization has various components: the functions pro- 
vided by libraries and the system calls provided by the underlying operating system. In both of these there 
are two levels of detail: which interfaces are present and the definition of what an interface does. 


The definitive document in this area for Linux is The Linux Standards Base (LSB), which you can find at 
http://www. linuxbase.org or http://www. linux-foundation.org/en/LSB. Several versions of 
the standard have been issued, and work is ongoing. 


You can find a list of distributions that have passed the certification at http: //www. 1linux-foundation 
.org/en/Products. Various versions of Red Hat, SUSE, and Ubuntu are certified, but do remember it 
takes a while after a distribution is released for certification to be checked. The site also has a list of distri- 
butions that are undergoing testing, or only require some updates to pass the certification tests. 
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The Linux Standards Base defines (as of version 3.1) three areas for compliance: 


Q Core: The main libraries, utilities and some key file system locations. 


Qh — C++: The C++ libraries. 





Q Desktop: Additional files for desktop installs, principally various graphic libraries. 
The main area we are interested in is the Core part of the specification. 


The LSB specification covers a number of areas as part of its own documentation, but also refers to some 
external standards for particular interface definitions. The areas covered are 

Object formats for binary compatibility 

Dynamic linking standards 

Standard libraries, both base libraries and the X Window System libraries 

The shell and other command-line programs 


The execution environment, including users and groups 





COCocoovodo 


System initialization and run levels 


In this chapter, we are really only interested in the standard libraries, users, and system initialization, so 
those are the areas we look at here. 


LSB Standard Libraries 


The Linux Standard Base defines the interfaces that must be present in two ways. For some functions, pri- 
marily those that are implemented by the GNU C library or tend to be Linux-only standards, it defines the 
interface and its behavior. For other interfaces, mostly those that come from Linux being UNIX-like, the 
specification simply states that a particular interface must be present and must behave as defined by another 
standard, usually that of the Common Application Environment (CAE) or more commonly The Single UNIX 
Specification, which is available from The Open Group, http: //www. opengroup. org. Some parts are 
available (currently registration is required) on the web at http: //www.unix.org/online.html. 


Unfortunately, the underlying standards for Linux, the UNIX standards, have a rather complex past, and 
rather too many standards to choose from, although mostly the various versions of the standards are 
closely compatible. 


A Brief History Lesson 


UNIX started in the late 1960s at AT&T Bell Laboratories, when Ken Thompson and Dennis Ritchie 
wrote an operating system, originally intended only for their personal use, that they called Unics. The 
name somehow changed into UNIX. AT&T allowed universities to have the source code for their own 
research, and UNIX quickly became extremely popular because of its very clean design and powerful 
concepts. The fact that the source code was available must also have been a significant incentive because 
it allowed people to make changes and experiment. 
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The BSD operating system was a variant that came out of work done at the University of California at 
Berkeley, where a lot of work was being done on networking. 


When AT&T started to make UNIX commercial, which occurred mostly around the mid 1980s, it termed 
its releases UNIX System, and the most popular was UNIX System V. 


Many other variants also appeared, far too numerous to list here, all of which had slight differences 
from and additions to the base standards, as companies have tried to add value by making proprietary 
extensions. 


Things started to get really complicated when AT&T sold its UNIX business to Novell, which, in 1994, 
decided to exit the UNIX business, and the ownership of the rights and trademarks became somewhat 
confused and the subject of various court cases. 


In 1988 the IEEE (http: //www. ieee. org) issued the first of a set of standards: the POSIX, or IEEE 1003, 
standards, which were intended to be a definitive portable interface specification for computer environ- 
ments. Although it’s a good and well-defined standard, POSIX is also very much a core specification and 
is quite limited in scope. 


In 1994 the X/OPEN Company, a vendor-neutral organization, produced a much larger set of specifications, 
the X/OPEN CAE, or Common Applications Environment, which is a superset of the IEEE POSIX standards 
and is technically identical to it in many areas. The X/OPEN company later merged with the OSF to found 
The Open Group; its home page is at http: / /www. opengroup.org/. The CAE standard was updated and 
released in 2002 as The Single UNIX Specification, Version 3, available from The Open Group. 


It is this specification to which the Linux standards base most frequently refers. 


It should be noted that “Linux” is a trademark, owned by Linus Torvalds (see http: / /www 
. linuxmark.org/). 


Using the LSB Standard for Libraries 


That’s enough about history of the standards. What does this mean for people writing C (or C++) pro- 
grams that they want to be portable? 


First, you should check that the library function you are using is listed in the LSB specification. If it isn’t 
there, you may well be doing something that is not going to port easily, and you should look for a stan- 
dard way of performing whatever you are trying to achieve. You might like to try the apropos Linux 
command, which searches the online manual pages for appropriate references. 


Second, and more difficult, is to check that the function behavior you are using is part of the specifica- 
tion, and you are not relying on behavior that is not specified. You may have to refer to The Single UNIX 
Specification to do this if the function usage is not defined by the LSB. 


A particularly good place to check for undefined or possibly erroneous behavior is the online Linux 
manuals. Many of the pages have a BUGS section, which is an invaluable source of information about 
where a particular call in Linux may not perfectly implement the standards or where there are known 
defects or oddities in behavior. 
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LSB Users and Groups 


This section of the specification is nice and brief, and very easy to understand. Following are a few of the 


specifications: 





Q The specification tells us never to read files like /etc/passwd directly, but to always use the stan- 
dard library calls such as getpwent, or standard utilities like passwd for accessing user details. 


Q It tells us that there must be a user called root in the root group, and that root is an adminis- 


trative user with full privileges. We also discover that there are a number of optional user and 
group names that should never be used by standard applications; they are intended for use 
by distributions. 


ū It also tells us that user IDs below 100 are system accounts, 100-499 are allocated by system 
administrators and post-install scripts, and 500 and higher are for normal user accounts. 


Generally, that is about all most Linux programmers need to know about the standards for users. 


LSB System Initialization 


The area of system initialization has always, at least to us, been an annoyance because of subtle differ- 
ences between distributions. 


Linux has inherited from UNIX-like operating systems the idea of run levels that define the services that 
are running at any time. For Linux, the usual definitions are given in the following table. 


Run Level 
0 


1 


Used for 
Halt. Used as a logical state to change to when the system is shut down. 


Single user mode, directories other than / may not be mounted, and net- 
working will not be enabled. It is normally used for system maintenance. 


Multiuser mode; however, networking is not enabled. 


Normal multiuser mode with networking, using a text mode 
login screen. 


Reserved. 
Normal multiuser mode with networking and a graphical login screen. 


A pseudo-level used for rebooting. 


The LSB lists these levels but doesn’t require them to be used, although they are very common. 


Accompanying these run levels is a set of initialization scripts used to start, stop, and restart services. 
Previously these have lived in various locations under /etc, often /etc/init.dor /etc/rce.d/init.d. 
This variation was often a source of confusion, because people who changed distributions could no longer 
find the initialization scripts where they expected to find them, and install programs failed while trying to 
put initialization scripts in the wrong directory. 
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The LSB 3.1 defines the location of these initialization scripts as /etc/init .d, though it does allow this 
to be a link to a different location. 


Each script in /etc/init.d has a name that relates to the service it provides. Because this is a common 
namespace that all services on Linux must share, it’s important that names are unique. For example, life 
would get difficult if both MySQL and PostgreSQL decided to call their scripts “database.” To avoid this 
conflict there is another set of standards. This is The Linux Assigned Names And Numbers Authority 
(LANANA), which you can find at http: //www.lanana.org/. Fortunately, you need to know very 
little about it except that they keep a list of registered names for scripts and packages, and thereby make 
life easier for users of Linux systems. 


An initialization script must take a parameter that controls what it should do. The defined parameters 
are as follows: 


Parameter Meaning 

start Start (or restart) the service. 

stop Stop the service. 

restart Restart the service; this is commonly implemented as simply a stop fol- 


lowed by a start of the service. 


reload This should reset the service, reloading any parameters, without actually stop- 
ping the service. Not all services can support this option, so this parameter 
may not be accepted by all scripts, or may be accepted but have no effect. 


force-reload This attempts to cause a reload if the service supports it, but if not, it does 
a restart. 
status This prints a textual message about the status of the service and returns 


a status code that can be used to determine the status of the service. 


All commands return 0 on success, or an error code indicating the reason for failure. In the case of status, 
0 is returned if the service is running; all other codes indicate the service is not running for some reason. 


The Filesystem Hierarchy Standard 


The last of the standards we are going to look at in this chapter is the Filesystem Hierarchy Standard 
(FHS), which you can find at http: //www.pathname.com/fhs/. 


The purpose of this standard is to define standard places in the Linux file system, so that developers 
and users alike can have reasonable expectations of where to find things. Long-time users of the various 
UNIX-like operating systems have long bemoaned the subtle differences between the way file systems 
are laid out, and the FHS provides a way for Linux distributions to avoid going down the same frag- 
mented path. 
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The arrangement of files in a Linux system may seem at first to be a semi-arbitrary arrangement of files 
and directories, based on historic practice. To an extent that’s true, but over the years the layout has 

evolved for good reasons into the hierarchy we see today. The general idea is to separate files and direc- 
tories into three groups: 





Q Files and directories that are unique to a particular system running Linux, such as start-up 
scripts and configuration files 


Q Files and directories that are read-only and may be shared between systems running Linux, 
such as application executables 


Q Directories that are read/write, but may be shared between systems running Linux or other 


operating systems, such as user home directories 


In this book, we are not overly interested in sharing files among different versions of Linux, although, 
where a network of Linux machines is in use, it can be an excellent way of ensuring that only a single 
copy of the key program directories exists, and of sharing that among many machines. This is particu- 


larly useful for diskless workstations. 


The top-level structure is defined by FHS to have several mandatory subdirectories and a small number 
of optional directories; the main ones are shown in the following table. 


Directory 
/bin 
/boot 
/dev 
/etc 
/home 
/lib 


/media 


/mnt 


/opt 
/root 


/sbin 


/Stv 


/tmp 
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Required? 


Peles es be 


Use 

Important system binary files. 
Files required to boot the system. 
Devices. 

System configuration files. 
Directories for user files. 
Standard libraries. 


A place for removable media to be mounted, with separate 
subdirectories for each media type supported by the system. 


A convenient point to temporarily mount devices, such as 
CD-ROMs and flash memory sticks. 


Additional application software. 
Files for the root user. 


Important system binary files that are required during sys- 
tem startup. 


Read-only data for services provided by this system. 


Temporary files. 
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Directory Required? Use 


/usr 


/var 


Y A secondary hierarchy. Traditionally user files were also 
stored here, but that is now considered bad practice, and 
/usr should not be writable by ordinary users. 


Y Variable data, such as log files. 


In addition, there can be other directories starting with 1ib, although this is not common. You will also 
usually see a /lost+found directory (for file system recovery by fsck) and a /proc directory, which 
is a pseudo file system, providing a mapping into the current running system. The /proc file system is 


strongly 


encouraged by the current version of FHS standard, but is not required to be present. Details of 


the /proc system are generally beyond the scope of this book, though we took a brief tour in Chapter 4. 


Here we 


Q 


look briefly at the purposes of each of the standard subdirectories of the / (root) directory: 


/bin — This contains binary files that can be used both by the root user and ordinary users, but 
are essential to operation in single-user mode, when some other directory structures may not be 
mounted. For example, core commands such as cat and 1s would normally be found in here, 
as will sh. 


/boot — This directory is used for files required during booting of the Linux system. It is fre- 
quently quite small, less than 100 MB, and often a separate partition. This is handy on PC-based 
systems, where there are frequently BIOS limitations on the active partition, requiring it to be in 
the first 2 G or 4 G of the disk. Having this as a separate partition allows more flexibility when 
deciding how to lay out the rest of the disk partitions. 


/dev — This contains the special device files that map to hardware. For example, /dev/hda will 
be mapped to the first IDE disk. 


/etc — This contains configuration files. Historically some binaries could also be found in here, 
but that is no longer true on most Linux systems. The best known file in the /etc directory is 
probably passwd, which contains information on users. Other useful files are fstab, listing 
mount options; hosts, listing IP to host name mappings, and the httpd directory, which con- 
tains configuration for the Apache server. 


/home — This is a directory for user files. Normally each user will have a single directory under this 
directory with the same name as their login, and this will be their default login directory. For exam- 
ple, after logging in, the user rick will almost certainly find himself in the /home/rick directory. 


/1ib — This contains essential shared libraries and kernel modules, specifically those that will 
be required while the system is booting or in single-user mode. 


/media — This is intended as a top-level directory to contain other directory mount points for 
removable media. The intention is to remove unnecessary top-level directories, such as /cdrom 
and /floppy. 


/mnt — This is simply a convenient place for mounting additional file systems temporarily. 
Historically some distributions have added subdirectories for the different devices, such as 
/cdromand /£loppy under /mnt, but the preferred location for these is now under /media, 
returning /mnt to its original purpose, as a single top-level temporary mount location. 
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Q 


/opt — This is a directory for software vendors to use when adding additional software appli- 
cations to the base distribution. Distributions should not use it for software they distribute as 
part of the standard distribution, but leave it free for third-party vendors to use. Generally, ven- 
dors will create a subdirectory with their name, and then further subdirectories such as /bin 
and /1ib for files specific to their application. 


By convention, many Open Source Linux packages use /usxr/1local for installation. 


m) 





m) 





/root — This is for files used by the root user. It is not in the /home directory part of the tree, 
because that may not be mounted in single-user mode. 


/sbin — This is used for commands normally used only by the system administrator, and 
required while the system is booting or in single-user mode. Commands such as fsck, halt, 
and swapon live here. 


/srv — This is intended as a location for site-specific read-only configuration data, however it 
is currently not in common use. 


/ tmp — This is used for temporary files. It is usually, but not always, cleared when the system 
is booted. 


/usr — This is a rather complex secondary file system, generally containing all the system-type 
commands and libraries not required during system booting or in single-user mode. It has many 
subdirectories, such as /bin, /lib, /X11R6, and /local. 


In the early days of UNIX and Linux, /usr also had subdirectories for logs, mail spooling, and the like. 
These have all now been removed from the usr directory and placed in the var directory. This has the 
advantage that /usx can now be a mountable file system, and in particular can be mounted read-only 
most of the time. When /usr is mounted read-only, it can be shared to other systems across a network 
and is less vulnerable to corruption should the system stop in an uncontrolled manner, perhaps because 
the power failed. 


Q 


/var — This contains data that changes frequently, such as spool files for printing, application 
log files, and mail-spooling directories. 


Further Reading about Standards 


There are, of course, many more things to consider if you want to write, and deploy, a fully portable 
Linux application. 


Do you want to localize your application so that it works with different languages and locales? Even 

if you stick to English, there are still the issues of currency, number separators, date formats, and many 
other considerations. There are, you guessed it, people working on those standards; you can see their 
work at http: //www.openil8n.org/. 


Another consideration is what options, library versions, and so forth the target system has installed. 
Fortunately, this problem is getting less acute, largely thanks to the standardization work we have 
looked at in this chapter, but it can still be a difficult problem. There are a pair of GNU tools which 
help considerably with this problem: autoconf and automake. Although you may not have used them 
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directly, you have almost certainly seen the benefits of them when installing software from source, when 
you typed ./configure; make. 


The use of these tools is beyond the scope of this book, but you can find more about them on the GNU web 
pages http: //www.gnu.org/software/autoconf/ and http: //www.gnu.org/software/automake. 


Summary 


In this final chapter, we have looked briefly at some of the many standards that are helping to make Linux 
an easier platform to program for, and that ensure that the many different distributions of Linux conform 
to some basic standards. Conforming to standards helps to make life easier for us, its programmers and 
users, and we urge you use the standards and to encourage others to do so. 
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SYMBOLS 


: command, 50 

. command, 51-52 

$# environment variable, 29 
$$ environment variable, 29 
$0 environment variable, 29 
/proc file system, 128-132 
$ shell prompt, 23 

> shell prompt, 23 

[ command, 31-34 


A 


Abiword, 646 

abusing memory, 260-261 

accept function, 618 

accept system call, 618 

addresses, socket addresses, 615-616 
address_len parameter, sockets, 618 
AF_APPLETALK socket domain, 615 
AF_INET socket domain, 612, 614 
AF_IPX socket domain, 615 

AF_ISO socket domain, 615 

AF_NS socket domain, 615 

AF_UNIX socket domain, 613-614, 614 
AIX, 2 

alarm clock program, 485-487 

AND list, 43-44 

Anjuta, 425 

apostrophes, 654 

applications, 8-9 

archives, 10-13 

argc, 137 

arguments, 137-140 

argv, 137 

assert macro, 452-453 

assertions, 452-453 

attrset function, curses library, 219 


Index 


backticks, 654 
bash shell, 19, 20 
version, 19 
Bell Laboraties, 1 
binary semaphores, 579 
Boolean data types, MySQL, 329 
Bourne shell, 19, 20 
box widgets, 658 
break command, 49-50 
breakpoints, debugging, 441-444 
built-in rules, makefiles, 387 
buttons, Qt 
QButton, 716-717 
QCheckBox, 717 
QPushButton, 717 
QRadioButton, 718 


C 


C#, GUIs and, 648 
C language 
compiler, Hello World, 7-8 
gcc options, 749-751 
GNU compiler, 749 
GTK+ and, 649 
history of, 748-749 
menu routines in, 176-177 
shell, 20 
CAE (Common Application Environment), 752 
callbacks 
GTK+, 655-658 
connecting, 656 
prototype, 656 
calloc function, 264 
canonical mode, terminal, 178 
case statement, 40-43 
catching signals, 481 





cbreak 


cbreak, curses library, 222 
CD management program, 693-697, 738-746 
application, 84-91 
summary, 574 
callbacks.c, 693-697 
cdapp.gnome.h, 688-689 
client interface functions, 558-564 
cliserv.h, 557-558 
curses library, 240-254 
dbm database and, 289-308 
design, 82-84 
GTK, 688-697 
interface.c, 689-693 
IPC facilities 
client functions, 602-603 
server functions, 600-602 
KDE, 738-746 
makefile, 553-554 
message queue status, 605 
MySQL 
access application data from C, 364-374 
add data to tables, 362-364 
table creation, 359-362 
pipes, 555-556 
client-side functions, 572-574 
implementation header, 569 
server-side functions, 569-572 
Qt, 738-746 
requirements, 82 
semaphore status, 604 
server.c, 565-568 
shared memory status, 604-605 
character data types, MySQL, 329 
characters, curses library, 218-221 
chdir system call, 122 
child processes, 466 
pipes and, 535-540 
chmod system call, 120 
chown system call, 120 
chreak function, curses library, 222 
ci command, 394 
clear function, curses library, 218 
clients, sockets 
multiple clients, 632-642 
select system call, 635-638 
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close system call, 619 
close system variable, 103 
closed pipes, reading, 536-537 
closedir function, 124 
closing sockets, 619 
co command, 394-395 
code 

critical sections, 577-578 

reuse, 18 
code inspection, debugging, 433 
coding errors, 430 
color, curses and, 235-238 
command line, dialog utility, 76 
commands 

:, 50 

., 51-52 

[, 31-34 

arithmetic expansion, 69-70 

break, 49-50 

ci, 394 

co, 394-395 

continue, 50-51 

echo, 52-53 

eval, 53 

exec, 53-54 

execution, 68-73 

exit, 25 

exit n, 54 

export, 54-55 

expr, 55-56 

find, 61-65 

grep, 65-66 

here documents, 73 

ident, 398-399 

kill, 482, 485 

make, 378 

man, 14 

netstat, 622 

parameter expansion, 70-73 

printf, 56-58 

ps, 462 

rcs, 393-394 

resdiff, 396-397 

return, 58 

rlog, 395-396 


rpmbuild, 415, 422-424 

set, 58 

shift, 58-59 

sort, 22 

trap, 59-61 

unset, 61 
comments, makefiles, 382 
competing locks, 276-280 
compiling, curses library and, 212-213 
conditions, 31 

[ command, 31-34 

test command, 31-34 
connections, sockets 

accepting, 617-618 

requesting, 618-619 
continue command, 50-51 
control structures 

case statement, 40-43 

elif statement, 35-36 

if statement, 34-35 

lists, 43-45 

for statement, 37-38 

statement blocks, 45-46 

until statement, 39-40 

while statement, 39 
cooked mode, curses library, 222 
Coordinated Universal Time (UTC), 151 
copying files, 104-106 
critical sections, 266, 577-578 
ctime function, 152-154 
curscr.stdscr, 213 
curses library, 211 

attrset function, 219 

cbreak, 222 

CD management program, 240-254 

characters, attributes, 218-221 

chreak function, 222 

chtype, 217 

clear function, 218 

clearing screen, 218 

color and, 235-238 

compiling and, 212-213 

cooked mode, 222 

curscr.stdscr, 213 

delwin call, 224 

echo function, 221 


CVS (Concurrent Versions System) 


endwin, 216 

erase function, 218 

Hello World program, 215 

inch function, 217 

initscr, 216 

innstr function, 217 

insch function, 217 

instr function, 217 

keyboard control, 221-222 
input, 222-224 

keypad, 232-235 

keypad mode, 233 

leaveok function, 218 

move function, 218 

moving cursor, 218 

newwin call, 224 

output to screen, 216-217 

pads, 238-240 

printw function, 217 

reading from screen, 217 

refresh function, 217 

screen refreshes, 229-230 

screens, 213 

stdscr, 213 

subwindows, 213, 230-232 
subwin function, 230 

versions, 212 

windows, 213 
creating, 224 
destroying, 224 
functions, 225 
moving, 225-229 
multiple, 226-229 
mvwin function, 225 
screen refreshes, 229-230 
scrollok function, 226 
touchwin, 226 
updating, 225-229 
wclear function, 226 
werase function, 226 
WINDOW structure, 224-225 
wrefresh function, 226 

CVS (Concurrent Versions System), 399-400 

front ends, 404-405 

local use, 400-403 

networks and, 403-404 
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daemons 


D 


daemons, Internet daemon, 629-631 
data types, MySQL 
Boolean, 329 
character, 329 
number, 329-330 
temporal, 330 
databases 
creating, MySQL, 328 
dbm database 
CD management program, 289-308 
datum type, 283 
dbm_clearerr function, 287 
dbm_close function, 284 
dbm_delete function, 287 
dbm_error function, 287 
dbm_fetch function, 284 
dbm_firstkey function, 288 
dbm_nextkey function, 288 
dbm_open function, 284 
dbm_store function, 284 
deleting from, 288-289 
introduction, 281-282 
reinstalling, 282 
retrieving from, 288-289 
routines, 283 
troubleshooting, 282 
writing program, 284-287 
datagram sockets, 614 
datagrams, 642-644 
_DATE_ macro, 434 
daytime service 
connecting to, 627-629 
datagrams and, 642 
dbm database 
CD management program, 289-308 
datum type, 283 
dbm_clearerr function, 287 
dbm_close function, 284 
dbm_delete function, 287 
dbm_error function, 287 
dbm_fetch function, 284 
dbm_firstkey function, 288 
dbm_nextkey function, 288 
dbm_open function, 284 
dbm_store function, 284 
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deleting from, 288-289 
introduction, 281-282 
reinstalling, 282 
retrieving from, 288-289 
routines, 283 
troubleshooting, 282 
writing program, 284-287 
DDL (data definition language), 331 
deadlocks, 280-281 
DEBUG macro, 434 
debugging 
breakpoints, setting, 441-444 
cflow, 450-451 
code inspection, 433 
controlled execution and, 436-437 
ctags, 449 
cxref, 449-450 
execution profiling, 451 
gdb 
breakpoints, 441-444 
listing program, 440-441 
patching and, 444-445 
running programs, 438 
stack trace, 438-439 
starting, 437-438 
variables and, 439-440 
instrumentation, 434-436 
lint, 446-449 
macros 
_DATE_, 434 
DEBUG, 434 
_FILE_, 434 
_LINE_, 434 
_TIME_, 434 
memory debugging, 453-454 
ElectricFence, 454-455 
valgrind, 455-458 
recompiling and, 435-436 
scripts, 74-75 
segmentation violation, 438 
stages, 430 
Dekker’s Algorithm, 578 
deleting, files, 94 
dependencies 
make command, 379-380 
makefiles, 378, 379-380 
RPM, 419 


eval command 


design errors, 430 
detached threads, 512 
/dev/console, 95 
/dev/null, 96 
/dev/tty, 95 
terminal and, 181-182 
development environments, 424-426 
Anjuta, 425 
Eclipse, 425 
KDevelop, 425 
QtEZ, 425 
SlickEdit, 425 
device drivers, 96-97 
devices, 95-96 
dialog utility, 75-81 
command line, 76 
output, 77 
dialogs, 727-728 
GtkDialog, 682-684 
modal dialog box, 684-685 
nonmodal, 685-686 
QDialog, 728 
modal dialogs, 728-729 
nonmodal dialogs, 729 
semimodal dialogs, 729-730 
QInputDialog, 731-733 
QMessageBox, 730-731 
difftime function, 150 
directories, 94-95 
scanning, 122 
closedir, 124 
opendir function, 123 
program for, 124-126 
readdir function, 123 
seekdir function, 124 
telldir, 123 
subdirectories, 94 
makefiles and, 391 
distributing software 
patch, 410-411 
as source code, 410 
utilities, 411-413 
documents, here documents, 73-74 
dpkg utility, 424 
drivers. See device drivers 
terminal, 182-183 


dup system call, 108-109 

pipes and, 538-540 
dup2 system call, 108-109 
duplicating process images, 472-475 


E 


echo command, 52-53 
echo function, curses library, 221 
Eclipse, 425 
ElectricFence, 454-455 
elif statement, 34-35 
Emacs, 6 
endwin, curses, 216 
environ variable, 147-148 
environment variables, 29, 144-146 
$#, 29 
$$, 29 
$0, 29 
environ, 147-148 
$HOME, 29 
$IFS, 29 
$PATH, 29 
$PS1, 29 
$PS2, 29 
using, 146-147 
environments 
development environments, 424-426 
Anjuta, 425 
Eclipse, 425 
KDevelop, 425 
QtEZ, 425 
SlickEdit, 425 
multitasking, 137 
erase function, curses library, 218 
errno variable, 119 
threads and, 497 
error handling, MySQL, 341-342 
errors 
coding errors, 430 
design errors, 430 
perror function, 127-128 
specification, 429 
stream, stdio library, 119 
strerror function, 127 
eval command, 53 


events 


events, GTK+, 655-658 

exec command, 53-54 
pipes and, 535-536 

exec function, 470 

execlp call, 471-472 

executable scripts, 25-26 

executables, 5 

executing commands, 68-73 

execution profiling, 451 

exit command, 25 

exit n command, 54 

export command, 54-55 

expr command, 55-56 
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fclose 1/0 function, 111 
fentl system call, 132-133, 268 
locking files, 271-273 
ferror function, 119 
fflush 1/0 function, 111 
fgetc 1/0 function, 112 
F_GETLK command, 270 
fgets 1/0 function, 113 
FHS (Filesystem Hierarchy Standard), 755-758 
FIFOs, 541 
accessing, 542-543 
client/server, 549-553 
inter-process communication with, 547-549 
open call and, 543-545 
reading, 546-549 
writing, 546-549 
file descriptors 
creating, 100-101 
output, 21 
streams and, 119-120 
_FILE_ macro, 434 
file-region locking, 268 
file-segment locking, 268 
filenames, libraries, 10 
files 
copying, 104-106 
deleting, 94 
devices and, 95-96 
directories, 94-95 
header files, 9 
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inode, 94 
library files, 9-10 
locking, 264-265 
deadlocks, 280-281 
fentl call, 268, 271-273 
F_GETLK command, 270 
file-region locking, 268 
file-segment locking, 268 
F_SETLK command, 270-271 
F_SETLKW command, 271 
lock files, cooperative, 266-268 
lock files, creating, 265-268 
lockf call, 268, 280 
read call, 271 
testing locks, 273-276 
write call, 271 
package files, RPM, 414-415 
system calls, 96-97, 98-99 
dup, 108-109 
fstat, 106-108 
ioctl, 97, 104 
Iseek, 106 
Istat, 106-108 
open, 100-101 
read, 99-100 
stat, 106-108 
write, 98-99 
temporary, 156-157 
tmpfile function, 156-157 
tmpnam function, 156-157 
user information, 158-161 
find command, 61-65 
fopen 1/0 function, 110 
for statement, 37-38 
wildcard expansion and, 38 
fork 
pipes and, 533-534 
processes and, 472-474 
threads, 495 
zombie processes, 477-478 
fprintf 1/0 function, 113-115 
fputc 1/0 function, 112 
fread 1/0 function, 111 
free call, 262 
Free Software Foundation, 3 


FreeBSD, 2 
freeing memory, 262-264 
fscanf 1/0 function, 115-117 
fseek 1/0 function, 112 
F_SETLK command, 270-271 
F_SETLKW command, 271 
fstat system call, 106-108 
functions, 46. See also 1/0 functions 

accept, 618 

closedir, 124 

ctime, 152-154 

defining, 47 

difftime, 150 

exec, 470 

ferror, 119 

getchoice, 177, 203-204 

getenv, 145-146 

gethostname, 161 

getlogin, 158 

getopt, 140-142 

getopt_long, 142-144 

getpriority, 169 

getrlimit, 170 

getrusage, 169 

getuid, 158 

gmtime, 150-152 

htonl, 623 

htons, 623 

library functions, 97-98 

local keyword, 47 

logmask, 166-167 

mkfifo, 542 

mktemp, 157 

mmap, 133-135 

msgct, 596-597 

msgget, 594-595 

msgrcv, 595-596 

msgsnd, 595 

opendir, 123 

openlog, 166 

parameters, 47 

pclose, 527 

perror, 127-128 

pipe, 531-534 

popen, 526-527 

putenv, 145-146 


readdir, 123 
returning numeric values, 47 
returning values, 48-49 
seekdir, 124 
semaphores, 580 
semctl, 582 
sem_destroy, 504 
semeget, 581 
semop, 581-582 
sem_post, 504 
sem_wait, 504 
setpriority, 169 
setrlimit, 170 
setsockopt, 631-632 
shmat, 588-589 
shmctl, 589-590 
shmdt, 589 
shmget, 588 
sigaddset, 489 
sigdelset, 489 
sigemptyset, 489 
sigfillset, 489 
sigismember, 489 
sigprocmask, 489 
sigsuspend, 490 
strerror, 127 
strftime, 153-154, 154-155 
strptime, 154-155 
syslog, 164-165 
telldir, 123 
time, 148-150 
tmpfile, 156-157 
tmpnam function, 156-157 
uname, 161 

fwrite 1/0 function, 111 
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gcc compiler, C options, 749-751 


gcc compiler, GNU make and, 391-392 


gdb 
listing program, 440-441 
patching and, 444-445 
running programs, 437-438 
stack trace, 438-439 
starting, 437-438 
variables and, 439-440 





general semaphores 


general semaphores, 579 
getc 1/0 function, 112 
getchar 1/0 function, 112, 178 
getchoice function, 177, 203-204 
getcwd system call, 122 
getenv function, 145-146 
gethostname function, 161 
getlogin function, 158 
getopt function, 140-142 
getopt_long function, 142-144 
getpriority function, 169 
getrlimit function, 170 
getrusage function, 169 
gets 1/0 function, 113 
getty program, 466 
getuid function, 158 
get_window_set_position, 662 
Gimp, 4 
GIMP (GNU Image Manipulation Program), 651 
globbing, 23 
gmtime function, 150-152 
GNOME, 4, 646 

introduction, 651-652 

libraries, installing, 652-655 

menus, 677-682 

code, 679-681 
macros, 681-682 

widgets, 676-677 

windows, 677 
GnomeApp widget, 677 
gnome_program_init, 676 
GNOMEUIlInfo structs, 677 
GnomeulinfoTypes, 678 
GNU (GNU’s Not Unix), 3 

C compiler, 749 
GNU make 

gcc compiler and, 391-392 

RCS and, 398 
GObject library, 650 
grant command (MySQL), 325-326 
Greeewich Mean Time, 151 
grep command, 65-66 
groff, manual pages, 408 
GTI (General Terminal Interface), 183 

hardware, 183-184 
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GTK+, 648-649 
C and, 649 
callbacks, 655-658 
connecting, 656 
demo application, 653 
events, 655-658 
GLib type system, 649-650 
GObject library, 650 
GtkTreeView, 672-676 
inheritance, 650 
libraries, 649 
initializing, 654 
installing, 652-655 
MVC design, 673 
object system, 650-651 
polymorphism, 650 
signals, 655-658 
GtkObject and, 655 
widgets, 661 
GtkEntry, 663-664 
GtkWindow, 662-663 
GtkAdjustment object, 667 
GtkBox, 658 
gtk_box_pack_end, 659 
gtk_box_pack_start, 659 
GtkButton, 657-658 
GtkCheckButton, 669-671 
GtkRadioButton, 669-671 
GtkToggleButton, 668-669, 669-671 
GtkButtonsType, 686 
GtkCellRenderer, 674 
GtkCheckButton, 669 
GtkDialog, 682-684 
GtkWindow and, 682 
simple dialog boxes, 686 
GTK_DIALOG_MODAL, 684 
gtk_dialog_new_with_buttons, 684 
gtk_dialog_run, 684 
GtkEntry, 663-664 
password entry, 664-666 
username entry, 664-666 
gtk_entry_append_text, 663 
gtk_entry_get_text, 663 
gtk_entry_modify_text, 663 
gtk_entry_new, 663 
gtk_entry_new_with_max_length, 663 








gtk_entry_set_invisible_char, 664 
gtk_entry_set_text, 663 
gtk_entry_set_visibility, 664 
GtkHBox, 658 
GtkHScale, 667 
GtkLabel, 670 
GtkMessageDialog, 686-687 
GTK_MESSAGE_OTHER, 686 
GtkObject, signals and, 655 
GTK_RESPONSE_ACCEPT, 683 
GTK_RESPONSE_NONE, 684 
GTK_RESPONSE_REJECT, 683 
GtkSpinButton, 666-668 
gtk_spin_button_new, 667 
GtkTreelter, 673 
GtkTreeStore, creating, 673 
GtkTreeView, 672-676, 674-676 
GtkCellRenderer, 672 
GtkTreeModel, 672 
GtkTreeViewColumn, 672 
GtkVBox, 658 
GtkVScale, 667 
GtkWidgets, 654 
gtk_widget_show, 684 
GtkWindow, 653-655, 662-663 
size, 663 
GTK_WINDOW_POPUP, 655 
gtk_window_set_default_size, 663 
gtk_window_set_title, 662 
gtk_window_show, 662 
GTK_WINDOW_TOPLEVEL, 655 
GUls 
creating, 648 
widgets, 658 


handling redirected output, 179-180 
header files, 9 

Hello World C program, 7-8 

here documents, 73-74 

SHOME environment variable, 29 
host information, 161-163 

host ordering, 622-623 

HP-UX, 2 

htonl function, 623 

htons function, 623 
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1/0 functions 

fclose, 111 

fflush, 114 

fgetc, 112 

fgets, 113 

fopen, 110 

fprintf, 113-115 

fputc, 112 

fread, 110-111 

fscanf, 115-117 

fseek, 112 

fwrite, 111 

getc, 112 

getchar, 112,178 

gets, 113 

printf, 113-115 

putc, 112 

putchar, 112 

scanf, 115-117 

sprintf, 113-115 

sscanf, 115-117 
1/0 system calls, 109 
ident command, 398-399 
IEEE (Institute of Electrical and Electronic 

Engineers), 2 

POSIX committee, threads and, 496 
if statement, 34-35 
SIFS environment variable, 29 
images, process 

duplicating, 472-475 

replacing, 470-472 
inch function, curses library, 217 
info, 14-16 
initscr, curses, 216 
InnoDB storage engine, 315 
innstr function, curses library, 217 
inode, 94 
input 

pipes and, 537-540 

redirecting, 22 

processes, 479-480 

insch function, curses library, 217 
installation, Qt, 702-705 
instr function, curses library, 217 
instrumentation, debugging, 434-436 
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interactive programs, 23-24 
interfaces, signals, 487-489 
Internet daemon, 629-631 
ioctl system call, 97, 104 
IP addresses 
determining, 624 
socket domains, 612-613 
IP (Internet Protocol), socket domains and, 
612-613 
IP ports, 613 
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Java, GUIs and, 648 


K 


KAction widget, 734 
kbhit, 205-207 
KDE, 4, 646 
CD management program, 738-746 
menus and, 733-734 
code, 735-737 
Qt and, 701-702 
toolbars and, 733-734 
code, 735-737 
widgets, 702 
KAction, 734 
KDevelop, 425 
kernel, memory allocation and, 259 
keyboard, input, curses library, 222-224 
keys, semaphores, 581 
keystroke detection, 205-207 
pseudo-terminals, 208 
virtual consoles, 207-208 
keywords 
local, 47 
MySQL, table creation, 331 
kill command, 482, 485 
Korn shell, 20 
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languages, 5 

Idd, 14 

Id.so, 14 

leaveok function, curses library, 218 
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libraries, 9-10 
curses, 211 
compiling and, 212-213 
filenames, 10 
GNOME, installing, 652-655 
GTK+, 649 
initializing, 654 
installing, 652-655 
LSB, 752-753 
make command and, 389-390 
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